Generate Swagger description for service methods using proto comments. #134
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.
ivucica
force-pushed
the
swagger_descriptions
branch
from
54ce68e
to
d2fd8af
Compare
…essages using proto comments
ivucica
force-pushed
the
swagger_descriptions
branch
from
7f238a4
to
24d2323
Compare
Also, fixed a few typos and renamed protoPath into protoPathIndex (as we are not returning the entire path in that method).
ivucica
force-pushed
the
swagger_descriptions
branch
from
69fc4e5
to
8bdac72
Compare
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.
ivucica
force-pushed
the
swagger_descriptions
branch
from
e410aec
to
bdceda1
Compare
|
Please let me know if something else is needed for this PR. |
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'.
|
@ivucica IMO you should separate the comment handling from this new |
|
What do you think about simply taking the last portion of the comment and if it's a json document integrate it. |
|
@tmc That sounds like a great idea. I'll work on that, including separating it into a separate PR. |
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
May 7, 2016
Depends on PR grpc-ecosystem#134. Reverts 562956f.
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
May 7, 2016
…agger: '. Per discussion in grpc-ecosystem#134.
ivucica
force-pushed
the
swagger_descriptions
branch
from
6d157cc
to
562956f
Compare
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
May 7, 2016
…agger: '. Per discussion in grpc-ecosystem#134.
|
LGTM. I can merge this PR as soon as I or you resolve merge conflicts. |
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
Oct 9, 2016
Depends on PR grpc-ecosystem#134. Reverts 562956f.
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
Oct 9, 2016
…agger: '. Per discussion in grpc-ecosystem#134.
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
Feb 10, 2017
Depends on PR grpc-ecosystem#134. Reverts 562956f.
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
Feb 10, 2017
…agger: '. Per discussion in grpc-ecosystem#134.
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
Mar 7, 2017
Depends on PR grpc-ecosystem#134. Reverts 562956f.
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
Mar 7, 2017
…agger: '. Per discussion in grpc-ecosystem#134.
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
Oct 27, 2017
Depends on PR grpc-ecosystem#134. Reverts 562956f.
ivucica
added a commit
to ivucica/grpc-gateway
that referenced
this pull request
Oct 27, 2017
…agger: '. Per discussion in grpc-ecosystem#134.
adasari
pushed a commit
to adasari/grpc-gateway
that referenced
this pull request
Apr 9, 2020
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.
This PR adds support for extracting Swagger
descriptions from protobuf comments.This fixes #128.
ORIGINAL OUTDATED TEXT FOLLOWS
While this is a first step in resolving #128, this
needs to be cleaned up, and the same approach needs to be used for
messages, message fields, et al.
echo_service.protohas been annotated with extra comments in order todemo 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.
Aside from some uncleanliness and overzealous
panic()ing, I'm also (obviously) unhappy with line 444. Other generators seem to be producing and comparing paths by joining them into comma-separated strings. They're also putting all theSourceCodeInfo_Locations into amapindexed by paths.(However, one thing that line 444 is doing good is dynamically looking up path IDs for 'message' type, etc. Even though it's using reflection for it, other generators written in Go seem to like to copy these constants into their own source code, which feels even worse.)
(For interested readers: More info on how to assemble a
SourceCodeInfo_Locationis in google/protobuf's descriptor.proto.)Similar to #133, I was unable to regenerate protobufs usefully. I fully expect Travis build to fail at this point.