Generate Swagger description for service methods using proto comments. #156
Conversation
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
While this is a first step in resolving grpc-ecosystem#128, this needs to be cleaned up, and the same approach needs to be used for messages, message fields, et al. echo_service.proto has been annotated with extra comments in order to demo the new descriptions. Only the Swagger example has been regenerated, as my local generator does not output all the expected fields in proto struct tags.
…essages using proto comments
Also, fixed a few typos and renamed protoPath into protoPathIndex (as we are not returning the entire path in that method).
This field should generally be non-nil while running the generator. This commit also adds a trivial check to make panic more informative in case a future test breaks in a similar fashion.
This patch will extract summary separately from description in Swagger objects that happen to support both summary and description. It will do so by splitting the relevant proto comment based on paragraphs, and using the first paragraph as the summary. This patch will also allow updating the Swagger schema's otherwise hard-to-map fields by allowing custom JSON to be placed within the proto comment. The syntax leaves something to be desired, but it works. Use of JSON is, on the other hand, rather universal. This patch will also allow describing the whole API by attaching the comments to the 'package' stanza inside the proto. In this case, summary will be applied to info.title, and description will be applied to info.description. Other properties have to be set through JSON. Schema has been slightly updated to allow for fields such as termsOfService, contact, license, externalDocs, etc. If a method is not documented, stub summary for Swagger Operation is no longer generated. Documentation for enum values is now multiline with dashes before values.
While the spec does not seem to dictate this, most of the examples seem to have HTTP status codes as the keys. This patch replaces the text 'default' with value of '200'.
adasari
pushed a commit
to adasari/grpc-gateway
that referenced
this pull request
Apr 9, 2020
Generate Swagger description for service methods using proto comments.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Resolved merge-conflicts in #134