From a84adaa12633071b85cdb1645d71007f8338f0cb Mon Sep 17 00:00:00 2001 From: godcong Date: Sat, 9 Nov 2024 04:22:26 +0800 Subject: [PATCH] docs(openapi): add OpenAPI documentation for greeter services - Add comprehensive OpenAPI 3.0.3 documentation for HelloGreeterAPI and SecondGreeterAPI - Include definitions for all API endpoints, request/response models, and error handling - Generate OpenAPI YAML using protoc-gen-openapi plugin - Update buf.gen.yaml configuration for OpenAPI generation --- buf.gen.yaml | 5 +- resources/docs/openapi/openapi.yaml | 577 ++++++++++++++++++++++++++++ 2 files changed, 581 insertions(+), 1 deletion(-) create mode 100644 resources/docs/openapi/openapi.yaml diff --git a/buf.gen.yaml b/buf.gen.yaml index b957500..d86b527 100644 --- a/buf.gen.yaml +++ b/buf.gen.yaml @@ -10,6 +10,7 @@ managed: # disable: # - file_option: go_package_prefix # module: buf.build/bufbuild/protovalidate + plugins: # comment with error: duplicate generated file name "openapi.yaml". Generation will continue without error here and drop the second occurrence of this file, but please raise an issue with the maintainer of the plugin. - local: protoc-gen-openapi @@ -19,8 +20,10 @@ plugins: # - depth=2 # Recursion depth of the loop message. The default value is 2 # - default_response=false # Adds a default response message. If true, a default response is automatically added for actions using the google.rpc.Status message. This is useful if you use envoy or grpc-gateway for transcoding, as they use this type as the default error response. Default value: true. # - enum_type=string # Serialized type of enumeration type. Use "string" for string-based serialization. The default value is integer. - - output_mode=source_relative # Output file generation mode. By default, only one openapi.yaml file is generated in the output folder. Using "source_relative" generates a separate "[inputfile].openapi.yaml" file for each '[inputfile].proto' file. The default is: merged. + # - output_mode=source_relative # Output file generation mode. By default, only one openapi.yaml file is generated in the output folder. Using "source_relative" generates a separate "[inputfile].openapi.yaml" file for each '[inputfile].proto' file. The default is: merged. + # - output_mode=merge - fq_schema_naming=true # Schema named whether to add a package name, is true, will add a package name, for example: system. Service. V1. ListDictDetailResponse, otherwise as follows: ListDictDetailResponse. The default value is false. + strategy: all - local: protoc-gen-go out: api/v1/services opt: paths=source_relative diff --git a/resources/docs/openapi/openapi.yaml b/resources/docs/openapi/openapi.yaml new file mode 100644 index 0000000..97f924f --- /dev/null +++ b/resources/docs/openapi/openapi.yaml @@ -0,0 +1,577 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: "" + version: 0.0.1 +paths: + /api/v1/helloworld/greeter: + get: + tags: + - HelloGreeterAPI + description: ListGreeter lists Greeters + operationId: HelloGreeterAPI_ListGreeter + parameters: + - name: current + in: query + description: Current page + schema: + type: integer + format: int32 + - name: page_size + in: query + description: The number of lines per page + schema: + type: integer + format: int32 + - name: no_paging + in: query + description: Whether not paging + schema: + type: boolean + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.ListGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + post: + tags: + - HelloGreeterAPI + description: CreateGreeter creates a new Greeter + operationId: HelloGreeterAPI_CreateGreeter + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.GreeterData' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.CreateGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + /api/v1/helloworld/greeter/{id}: + get: + tags: + - HelloGreeterAPI + description: GetGreeter gets a Greeter + operationId: HelloGreeterAPI_GetGreeter + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.GetGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + put: + tags: + - HelloGreeterAPI + description: UpdateGreeter updates a Greeter + operationId: HelloGreeterAPI_UpdateGreeter + parameters: + - name: id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.GreeterData' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.UpdateGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + delete: + tags: + - HelloGreeterAPI + description: DeleteGreeter deletes a Greeter + operationId: HelloGreeterAPI_DeleteGreeter + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.DeleteGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + /api/v1/helloworld/greeter/{id}/hello: + get: + tags: + - HelloGreeterAPI + description: SayHello is a get method + operationId: HelloGreeterAPI_SayHello + parameters: + - name: id + in: path + required: true + schema: + type: string + - name: name + in: query + schema: + type: string + - name: data.id + in: query + schema: + type: string + - name: data.name + in: query + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.SayHelloResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + post: + tags: + - HelloGreeterAPI + description: PostHello is a post method + operationId: HelloGreeterAPI_PostHello + parameters: + - name: id + in: path + required: true + schema: + type: string + - name: name + in: query + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.GreeterData' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.helloworld.PostHelloResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + /api/v1/secondworld/greeter: + get: + tags: + - SecondGreeterAPI + description: ListGreeter lists Greeters + operationId: SecondGreeterAPI_ListGreeter + parameters: + - name: current + in: query + description: Current page + schema: + type: integer + format: int32 + - name: page_size + in: query + description: The number of lines per page + schema: + type: integer + format: int32 + - name: no_paging + in: query + description: Whether not paging + schema: + type: boolean + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.ListGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + post: + tags: + - SecondGreeterAPI + description: CreateGreeter creates a new Greeter + operationId: SecondGreeterAPI_CreateGreeter + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.GreeterData' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.CreateGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + /api/v1/secondworld/greeter/{id}: + get: + tags: + - SecondGreeterAPI + description: GetGreeter gets a Greeter + operationId: SecondGreeterAPI_GetGreeter + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.GetGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + put: + tags: + - SecondGreeterAPI + description: UpdateGreeter updates a Greeter + operationId: SecondGreeterAPI_UpdateGreeter + parameters: + - name: id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.GreeterData' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.UpdateGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + delete: + tags: + - SecondGreeterAPI + description: DeleteGreeter deletes a Greeter + operationId: SecondGreeterAPI_DeleteGreeter + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.DeleteGreeterResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + /api/v1/secondworld/greeter/{id}/hello: + get: + tags: + - SecondGreeterAPI + description: SayHello is a get method + operationId: SecondGreeterAPI_SayHello + parameters: + - name: id + in: path + required: true + schema: + type: string + - name: name + in: query + schema: + type: string + - name: data.id + in: query + schema: + type: string + - name: data.name + in: query + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.SayHelloResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' + post: + tags: + - SecondGreeterAPI + description: PostHello is a post method + operationId: SecondGreeterAPI_PostHello + parameters: + - name: id + in: path + required: true + schema: + type: string + - name: name + in: query + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.GreeterData' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/api.v1.services.secondworld.PostHelloResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' +components: + schemas: + api.v1.services.helloworld.CreateGreeterResponse: + type: object + properties: {} + api.v1.services.helloworld.DeleteGreeterResponse: + type: object + properties: {} + api.v1.services.helloworld.GetGreeterResponse: + type: object + properties: {} + api.v1.services.helloworld.GreeterData: + type: object + properties: + id: + type: string + name: + type: string + api.v1.services.helloworld.ListGreeterResponse: + type: object + properties: + success: + type: boolean + total: + type: integer + format: int32 + data: + type: array + items: + $ref: '#/components/schemas/api.v1.services.helloworld.GreeterData' + error: + $ref: '#/components/schemas/errors.rpcerr.Error' + extra: + $ref: '#/components/schemas/google.protobuf.Any' + api.v1.services.helloworld.PostHelloResponse: + type: object + properties: + data: + $ref: '#/components/schemas/api.v1.services.helloworld.GreeterData' + description: The response message containing the greetings + api.v1.services.helloworld.SayHelloResponse: + type: object + properties: + data: + $ref: '#/components/schemas/api.v1.services.helloworld.GreeterData' + description: The response message containing the greetings + api.v1.services.helloworld.UpdateGreeterResponse: + type: object + properties: + success: + type: boolean + data: + type: array + items: + $ref: '#/components/schemas/api.v1.services.helloworld.GreeterData' + api.v1.services.secondworld.CreateGreeterResponse: + type: object + properties: {} + api.v1.services.secondworld.DeleteGreeterResponse: + type: object + properties: {} + api.v1.services.secondworld.GetGreeterResponse: + type: object + properties: {} + api.v1.services.secondworld.GreeterData: + type: object + properties: + id: + type: string + name: + type: string + api.v1.services.secondworld.ListGreeterResponse: + type: object + properties: + success: + type: boolean + total: + type: integer + format: int32 + data: + type: array + items: + $ref: '#/components/schemas/api.v1.services.secondworld.GreeterData' + error: + $ref: '#/components/schemas/errors.rpcerr.Error' + extra: + $ref: '#/components/schemas/google.protobuf.Any' + api.v1.services.secondworld.PostHelloResponse: + type: object + properties: + data: + $ref: '#/components/schemas/api.v1.services.secondworld.GreeterData' + description: The response message containing the greetings + api.v1.services.secondworld.SayHelloResponse: + type: object + properties: + data: + $ref: '#/components/schemas/api.v1.services.secondworld.GreeterData' + description: The response message containing the greetings + api.v1.services.secondworld.UpdateGreeterResponse: + type: object + properties: + success: + type: boolean + data: + type: array + items: + $ref: '#/components/schemas/api.v1.services.secondworld.GreeterData' + errors.rpcerr.Error: + type: object + properties: + id: + type: string + code: + type: integer + format: int32 + detail: + type: string + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' +tags: + - name: HelloGreeterAPI + description: The greeting service definition. + - name: SecondGreeterAPI + description: The greeting service definition.