From 3731b9aebdc04d41ce79c3df61c3dcd69fd1ff6b Mon Sep 17 00:00:00 2001 From: Ben Wells Date: Sun, 31 May 2020 20:10:38 +0100 Subject: [PATCH] Add openapi protobuf documentation examples --- protoc-gen-openapiv2/options/openapiv2.pb.go | 122 ++++++++++++++++++- protoc-gen-openapiv2/options/openapiv2.proto | 122 ++++++++++++++++++- 2 files changed, 242 insertions(+), 2 deletions(-) diff --git a/protoc-gen-openapiv2/options/openapiv2.pb.go b/protoc-gen-openapiv2/options/openapiv2.pb.go index 26173c1b9bf..944b328c257 100644 --- a/protoc-gen-openapiv2/options/openapiv2.pb.go +++ b/protoc-gen-openapiv2/options/openapiv2.pb.go @@ -313,6 +313,28 @@ func (SecurityScheme_Flow) EnumDescriptor() ([]byte, []int) { // // 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: "none@example.com"; +// }; +// 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"; +// }; +// type Swagger struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -487,6 +509,27 @@ func (x *Swagger) GetExtensions() map[string]*_struct.Value { // // 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"; +// } +// } +// }; +// } +// } type Operation struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -736,6 +779,26 @@ func (x *Response) GetExtensions() map[string]*_struct.Value { // // 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: "none@example.com"; +// }; +// license: { +// name: "BSD 3-Clause License"; +// url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt"; +// }; +// }; +// ... +// }; +// type Info struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -843,6 +906,21 @@ func (x *Info) GetExtensions() map[string]*_struct.Value { // // 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: "none@example.com"; +// }; +// ... +// }; +// ... +// }; +// type Contact struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -915,6 +993,20 @@ func (x *Contact) GetEmail() string { // // 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"; +// }; +// ... +// }; +// ... +// }; +// type License struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -977,6 +1069,17 @@ func (x *License) GetUrl() string { // // 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"; +// } +// ... +// }; +// type ExternalDocumentation struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -1141,7 +1244,24 @@ func (x *Schema) GetExample() *any.Any { // 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." +// }]; +// } +// type JSONSchema struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache diff --git a/protoc-gen-openapiv2/options/openapiv2.proto b/protoc-gen-openapiv2/options/openapiv2.proto index e5d18e5c9fb..636e9fd057d 100644 --- a/protoc-gen-openapiv2/options/openapiv2.proto +++ b/protoc-gen-openapiv2/options/openapiv2.proto @@ -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: "none@example.com"; +// }; +// 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: "none@example.com"; +// }; +// 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: "none@example.com"; +// }; +// ... +// }; +// ... +// }; +// 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;