-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add openapi protobuf documentation examples
- Loading branch information
1 parent
003180e
commit 37d2faa
Showing
2 changed files
with
242 additions
and
2 deletions.
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -21,6 +21,28 @@ enum Scheme { | |
| // | ||
| // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#swaggerObject | ||
| // | ||
| // Example: | ||
| // | ||
| // option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { | ||
| // info: { | ||
| // title: "Echo API"; | ||
| // version: "1.0"; | ||
| // description: "; | ||
| // contact: { | ||
| // name: "gRPC-Gateway project"; | ||
| // url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| // email: "[email protected]"; | ||
| // }; | ||
| // license: { | ||
| // name: "BSD 3-Clause License"; | ||
| // url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt"; | ||
| // }; | ||
| // }; | ||
| // schemes: HTTPS; | ||
| // consumes: "application/json"; | ||
| // produces: "application/json"; | ||
| // }; | ||
| // | ||
| message Swagger { | ||
| // Specifies the OpenAPI Specification version being used. It can be | ||
| // used by the OpenAPI UI and other clients to interpret the API listing. The | ||
|
|
@@ -84,6 +106,27 @@ message Swagger { | |
| // | ||
| // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#operationObject | ||
| // | ||
| // Example: | ||
| // | ||
| // service EchoService { | ||
| // rpc Echo(SimpleMessage) returns (SimpleMessage) { | ||
| // option (google.api.http) = { | ||
| // get: "/v1/example/echo/{id}" | ||
| // }; | ||
| // | ||
| // option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { | ||
| // summary: "Get a message."; | ||
| // operation_id: "getMessage"; | ||
| // tags: "echo"; | ||
| // responses: { | ||
| // key: "200" | ||
| // value: { | ||
| // description: "OK"; | ||
| // } | ||
| // } | ||
| // }; | ||
| // } | ||
| // } | ||
| message Operation { | ||
| // A list of tags for API documentation control. Tags can be used for logical | ||
| // grouping of operations by resources or any other qualifier. | ||
|
|
@@ -153,6 +196,26 @@ message Response { | |
| // | ||
| // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#infoObject | ||
| // | ||
| // Example: | ||
| // | ||
| // option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { | ||
| // info: { | ||
| // title: "Echo API"; | ||
| // version: "1.0"; | ||
| // description: "; | ||
| // contact: { | ||
| // name: "gRPC-Gateway project"; | ||
| // url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| // email: "[email protected]"; | ||
| // }; | ||
| // license: { | ||
| // name: "BSD 3-Clause License"; | ||
| // url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt"; | ||
| // }; | ||
| // }; | ||
| // ... | ||
| // }; | ||
| // | ||
| message Info { | ||
| // The title of the application. | ||
| string title = 1; | ||
|
|
@@ -175,6 +238,21 @@ message Info { | |
| // | ||
| // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#contactObject | ||
| // | ||
| // Example: | ||
| // | ||
| // option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { | ||
| // info: { | ||
| // ... | ||
| // contact: { | ||
| // name: "gRPC-Gateway project"; | ||
| // url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| // email: "[email protected]"; | ||
| // }; | ||
| // ... | ||
| // }; | ||
| // ... | ||
| // }; | ||
| // | ||
| message Contact { | ||
| // The identifying name of the contact person/organization. | ||
| string name = 1; | ||
|
|
@@ -190,6 +268,20 @@ message Contact { | |
| // | ||
| // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#licenseObject | ||
| // | ||
| // Example: | ||
| // | ||
| // option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { | ||
| // info: { | ||
| // ... | ||
| // license: { | ||
| // name: "BSD 3-Clause License"; | ||
| // url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt"; | ||
| // }; | ||
| // ... | ||
| // }; | ||
| // ... | ||
| // }; | ||
| // | ||
| message License { | ||
| // The license name used for the API. | ||
| string name = 1; | ||
|
|
@@ -202,6 +294,17 @@ message License { | |
| // | ||
| // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#externalDocumentationObject | ||
| // | ||
| // Example: | ||
| // | ||
| // option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { | ||
| // ... | ||
| // external_docs: { | ||
| // description: "More about gRPC-Gateway"; | ||
| // url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| // } | ||
| // ... | ||
| // }; | ||
| // | ||
| message ExternalDocumentation { | ||
| // A short description of the target documentation. GFM syntax can be used for | ||
| // rich text representation. | ||
|
|
@@ -247,7 +350,24 @@ message Schema { | |
| // See also: https://cswr.github.io/JsonSchema/spec/basic_types/, | ||
| // https://github.com/json-schema-org/json-schema-spec/blob/master/schema.json | ||
| // | ||
| // TODO(ivucica): document fields | ||
| // Example: | ||
| // | ||
| // message SimpleMessage { | ||
| // option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = { | ||
| // json_schema: { | ||
| // title: "SimpleMessage" | ||
| // description: "A simple message." | ||
| // required: ["id"] | ||
| // } | ||
| // }; | ||
| // | ||
| // // Id represents the message identifier. | ||
| // string id = 1; [ | ||
| // (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { | ||
| // {description: "The unique identifier of the simple message." | ||
| // }]; | ||
| // } | ||
| // | ||
| message JSONSchema { | ||
| // field 1 is reserved for '$id', omitted from OpenAPI v2. | ||
| reserved 1; | ||
|
|
||