-
Notifications
You must be signed in to change notification settings - Fork 2.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add custom options to allow more control of swagger/openapi output #145
Merged
Merged
Changes from 22 commits
Commits
Show all changes
26 commits
Select commit
Hold shift + click to select a range
6ff06d8
Apply additional Swagger properties using JSON.
ivucica fcc2dca
Swagger: Replaced '<!-- ... -->' for raw JSON with last paragraph 'Sw…
ivucica 20a6d40
Change from 'Swagger: ' to 'OpenAPI: ' prefix.
ivucica 321663d
WIP: Use a proto option to describe whether a Swagger Operation is de…
ivucica 7043966
WIP: Setting API properties through an option.
ivucica cdc1094
WIP: Correctly reserve fields. Update link. TODO: merge with commit M…
ivucica 41b436f
WIP: Refer to the specification as OpenAPI v2, not Swagger.
ivucica 74cd394
WIP: Clean up after OpenAPIv2 options proto generation.
ivucica 549ccee
WIP: JSON is disappearing from the output protos.
ivucica 6b2b321
WIP: Fix typo 'want an Swagger' -> 'want a Swagger object'.
ivucica db4a056
WIP: Process all remaining fields of the OpenAPI v2 Swagger object.
ivucica 7697bcf
WIP: ExternalDocs belongs on OpenAPIv2's Swagger object, not on the I…
ivucica 162c375
WIP: Remove use of JSON. Introduce schema and tag object. Support ext…
ivucica b53579c
WIP: Add built annotations.pb.go and openapiv2.pb.go.
ivucica 60d116f
WIP: go fmt on protoc-gen-swagger.
ivucica d509096
WIP: Provide a more unique operation ID in case of additional bindings.
ivucica 3949620
WIP: Try to fix integration test by removing 'host' from the Swagger …
ivucica a386e97
WIP: Remove swaggerExtrasRegexp.
ivucica 290f777
WIP: Move error checking for extractSchemaOptionFromMessageDescriptor…
ivucica 97ee19b
WIP: Fix typo: 'want a Schema'.
ivucica ceb4c4e
Assign IDs for proto options extensions.
ivucica 099fda5
Move test definitions for options-based extension to Swagger output f…
ivucica d7b0ba4
Undo commenting out dependency on EXAMPLE_CLIENT_SRCS.
ivucica d7a9a69
Change the proto package to start with 'grpc.gateway', as seems to be…
ivucica 84c3046
Add a comment about all IDs being ok to be the same.
ivucica a543b9e
Regenerated Swagger-generated clients.
ivucica File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
Large diffs are not rendered by default.
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 |
|---|---|---|
|
|
@@ -8,10 +8,43 @@ import "google/protobuf/duration.proto"; | |
| import "examples/sub/message.proto"; | ||
| import "examples/sub2/message.proto"; | ||
| import "google/protobuf/timestamp.proto"; | ||
| import "protoc-gen-swagger/options/annotations.proto"; | ||
|
|
||
| option (grpc_gateway.protoc_gen_swagger.options.openapiv2_swagger) = { | ||
| info: { | ||
| title: "A Bit of Everything"; | ||
| version: "1.0"; | ||
| contact: { | ||
| name: "gRPC-Gateway project"; | ||
| url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| email: "[email protected]"; | ||
| }; | ||
| }; | ||
| // Overwriting host entry breaks tests, so this is not done here. | ||
| external_docs: { | ||
| url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| description: "More about gRPC-Gateway"; | ||
| } | ||
| schemes: HTTP; | ||
| schemes: HTTPS; | ||
| schemes: WSS; | ||
| consumes: "application/json"; | ||
| consumes: "application/x-foo-mime"; | ||
| produces: "application/json"; | ||
| produces: "application/x-foo-mime"; | ||
| }; | ||
|
|
||
|
|
||
| // Intentionaly complicated message type to cover much features of Protobuf. | ||
| // NEXT ID: 27 | ||
| message ABitOfEverything { | ||
| option (grpc_gateway.protoc_gen_swagger.options.openapiv2_schema) = { | ||
| external_docs: { | ||
| url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| description: "Find out more about ABitOfEverything"; | ||
| } | ||
| }; | ||
|
|
||
| // Nested is nested type. | ||
| message Nested { | ||
| // name is nested field. | ||
|
|
@@ -72,7 +105,18 @@ enum NumericEnum { | |
| ONE = 1; | ||
| } | ||
|
|
||
| // ABitOfEverything service is used to validate that APIs with complicated | ||
| // proto messages and URL templates are still processed correctly. | ||
| service ABitOfEverythingService { | ||
|
|
||
| option (grpc_gateway.protoc_gen_swagger.options.openapiv2_tag) = { | ||
| description: "ABitOfEverythingService description -- which should not be used in place of the documentation comment!" | ||
| external_docs: { | ||
| url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| description: "Find out more about EchoService"; | ||
| } | ||
| }; | ||
|
|
||
| rpc Create(ABitOfEverything) returns (ABitOfEverything) { | ||
| // TODO add enum_value | ||
| option (google.api.http) = { | ||
|
|
@@ -105,7 +149,21 @@ service ABitOfEverythingService { | |
| option (google.api.http) = { | ||
| get: "/v1/example/a_bit_of_everything/query/{uuid}" | ||
| }; | ||
| option (grpc_gateway.protoc_gen_swagger.options.openapiv2_operation) = { | ||
| deprecated: true // For testing purposes. | ||
| external_docs: { | ||
| url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| description: "Find out more about GetQuery"; | ||
| } | ||
| }; | ||
| } | ||
| // Echo allows posting a StringMessage value. | ||
| // | ||
| // It also exposes multiple bindings. | ||
| // | ||
| // This makes it useful when validating that the OpenAPI v2 API | ||
| // description exposes documentation correctly on all paths | ||
| // defined as additional_bindings in the proto. | ||
| rpc Echo(grpc.gateway.examples.sub.StringMessage) returns (grpc.gateway.examples.sub.StringMessage) { | ||
| option (google.api.http) = { | ||
| get: "/v1/example/a_bit_of_everything/echo/{value}" | ||
|
|
@@ -117,6 +175,12 @@ service ABitOfEverythingService { | |
| get: "/v2/example/echo" | ||
| } | ||
| }; | ||
| option (grpc_gateway.protoc_gen_swagger.options.openapiv2_operation) = { | ||
| external_docs: { | ||
| url: "https://github.com/grpc-ecosystem/grpc-gateway"; | ||
| description: "Find out more Echo"; | ||
| } | ||
| }; | ||
| } | ||
| rpc DeepPathEcho(ABitOfEverything) returns (ABitOfEverything) { | ||
| option (google.api.http) = { | ||
|
|
||
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 |
|---|---|---|
| @@ -1,18 +1,26 @@ | ||
| { | ||
| "swagger": "2.0", | ||
| "info": { | ||
| "title": "examples/examplepb/a_bit_of_everything.proto", | ||
| "version": "version not set" | ||
| "title": "A Bit of Everything", | ||
| "version": "1.0", | ||
| "contact": { | ||
| "name": "gRPC-Gateway project", | ||
| "url": "https://github.com/grpc-ecosystem/grpc-gateway", | ||
| "email": "[email protected]" | ||
| } | ||
| }, | ||
| "schemes": [ | ||
| "http", | ||
| "https" | ||
| "https", | ||
| "wss" | ||
| ], | ||
| "consumes": [ | ||
| "application/json" | ||
| "application/json", | ||
| "application/x-foo-mime" | ||
| ], | ||
| "produces": [ | ||
| "application/json" | ||
| "application/json", | ||
| "application/x-foo-mime" | ||
| ], | ||
| "paths": { | ||
| "/v1/example/a_bit_of_everything": { | ||
|
|
@@ -43,6 +51,8 @@ | |
| }, | ||
| "/v1/example/a_bit_of_everything/echo/{value}": { | ||
| "get": { | ||
| "summary": "Echo allows posting a StringMessage value.", | ||
| "description": "It also exposes multiple bindings.\n\nThis makes it useful when validating that the OpenAPI v2 API\ndescription exposes documentation correctly on all paths\ndefined as additional_bindings in the proto.", | ||
| "operationId": "Echo", | ||
| "responses": { | ||
| "200": { | ||
|
|
@@ -62,7 +72,11 @@ | |
| ], | ||
| "tags": [ | ||
| "ABitOfEverythingService" | ||
| ] | ||
| ], | ||
| "externalDocs": { | ||
| "description": "Find out more Echo", | ||
| "url": "https://github.com/grpc-ecosystem/grpc-gateway" | ||
| } | ||
| } | ||
| }, | ||
| "/v1/example/a_bit_of_everything/query/{uuid}": { | ||
|
|
@@ -264,7 +278,12 @@ | |
| ], | ||
| "tags": [ | ||
| "ABitOfEverythingService" | ||
| ] | ||
| ], | ||
| "deprecated": true, | ||
| "externalDocs": { | ||
| "description": "Find out more about GetQuery", | ||
| "url": "https://github.com/grpc-ecosystem/grpc-gateway" | ||
| } | ||
| } | ||
| }, | ||
| "/v1/example/a_bit_of_everything/{float_value}/{double_value}/{int64_value}/separator/{uint64_value}/{int32_value}/{fixed64_value}/{fixed32_value}/{bool_value}/{string_value}/{uint32_value}/{sfixed32_value}/{sfixed64_value}/{sint32_value}/{sint64_value}/{nonConventionalNameValue}": { | ||
|
|
@@ -498,7 +517,9 @@ | |
| }, | ||
| "/v2/example/echo": { | ||
| "get": { | ||
| "operationId": "Echo", | ||
| "summary": "Echo allows posting a StringMessage value.", | ||
| "description": "It also exposes multiple bindings.\n\nThis makes it useful when validating that the OpenAPI v2 API\ndescription exposes documentation correctly on all paths\ndefined as additional_bindings in the proto.", | ||
| "operationId": "Echo3", | ||
| "responses": { | ||
| "200": { | ||
| "description": "", | ||
|
|
@@ -517,10 +538,16 @@ | |
| ], | ||
| "tags": [ | ||
| "ABitOfEverythingService" | ||
| ] | ||
| ], | ||
| "externalDocs": { | ||
| "description": "Find out more Echo", | ||
| "url": "https://github.com/grpc-ecosystem/grpc-gateway" | ||
| } | ||
| }, | ||
| "post": { | ||
| "operationId": "Echo", | ||
| "summary": "Echo allows posting a StringMessage value.", | ||
| "description": "It also exposes multiple bindings.\n\nThis makes it useful when validating that the OpenAPI v2 API\ndescription exposes documentation correctly on all paths\ndefined as additional_bindings in the proto.", | ||
| "operationId": "Echo2", | ||
| "responses": { | ||
| "200": { | ||
| "description": "", | ||
|
|
@@ -541,7 +568,11 @@ | |
| ], | ||
| "tags": [ | ||
| "ABitOfEverythingService" | ||
| ] | ||
| ], | ||
| "externalDocs": { | ||
| "description": "Find out more Echo", | ||
| "url": "https://github.com/grpc-ecosystem/grpc-gateway" | ||
| } | ||
| } | ||
| }, | ||
| "/v2/example/timeout": { | ||
|
|
@@ -707,7 +738,11 @@ | |
| "title": "repeated enum value. it is comma-separated in query" | ||
| } | ||
| }, | ||
| "title": "Intentionaly complicated message type to cover much features of Protobuf.\nNEXT ID: 27" | ||
| "title": "Intentionaly complicated message type to cover much features of Protobuf.\nNEXT ID: 27", | ||
| "externalDocs": { | ||
| "description": "Find out more about ABitOfEverything", | ||
| "url": "https://github.com/grpc-ecosystem/grpc-gateway" | ||
| } | ||
| }, | ||
| "examplepbNumericEnum": { | ||
| "type": "string", | ||
|
|
@@ -731,5 +766,9 @@ | |
| } | ||
| } | ||
| } | ||
| }, | ||
| "externalDocs": { | ||
| "description": "More about gRPC-Gateway", | ||
| "url": "https://github.com/grpc-ecosystem/grpc-gateway" | ||
| } | ||
| } | ||
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
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't you need to import the relevant proto file to access options?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, that's annotations.proto, I see. I was confused by the package here, importing from
protoc-gen-swaggerand then accessing agrpc_gatewaynamespace. Might just be me but feels like a disconnect?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My approach for setting proto package name:
grpc_gatewayproject, and users may want some more uniqueness ->grpc_gatewayprotoc-gen-grpc-gatewayandprotoc-gen-swagger; this only applies to the latter ->protoc_gen_swaggeroptionsI'm not sure why I did not go for a fully global namespace
com.github.grpc_ecosystem.grpc_gateway..... Either way there's a variety of approaches taken.You did get me to look around so I will change this to use
grpc.gateway, as that seems to be used for the runtime and example protos.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sounds good to me :)