internal/proto: improvements to OpenAPIv2 spec #4555
Merged
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
|
|
johanbrandhorst
commented
Mar 21, 2024
internal/proto/controller/api/services/v1/account_service.proto
Outdated
Show resolved
Hide resolved
johanbrandhorst
commented
Mar 21, 2024
| url: "https://github.com/hashicorp/boundary/blob/main/LICENSE" | ||
| }; | ||
| } | ||
| host: "your-boundary-hostname.com" |
There was a problem hiding this comment.
We could have something like localhost:9200 here as well, not sure what makes this the most obvious that it depends on their Boundary deployment?
johanbrandhorst
changed the title
johanbrandhorst
requested review from
stellarsquall,
talanknight,
jefferai and
Dan-Heath
johanbrandhorst
changed the title
johanbrandhorst
force-pushed
the
jbrandhorst-api-docs-improvements
branch
from
5f0b8aa
to
187ccbb
Compare
talanknight
reviewed
Mar 25, 2024
internal/proto/controller/api/services/v1/account_service.proto
Outdated
Show resolved
Hide resolved
internal/proto/controller/api/resources/accounts/v1/account.proto
Outdated
Show resolved
Hide resolved
johanbrandhorst
force-pushed
the
jbrandhorst-api-docs-improvements
branch
from
187ccbb
to
24e3dbd
Compare
talanknight
approved these changes
Mar 25, 2024
Dan-Heath
requested changes
Apr 2, 2024
There was a problem hiding this comment.
Great work on this! This was a huge effort, many thanks to the whole API Docs Days team that worked on it. Our customers will greatly benefit from the more consistent presentation of resource names and other information. And I love that you included links to external docs where appropriate!
I added suggestions for style and standards. Please let me know if you have any questions about my feedback. Also, if you're short on time to follow up, I'd be happy to apply the updates. Just let me know how I can help.
Thank you!
Add various pieces of metadata that can be used by the API docs renderer. Improve the service labels by specifying explicit tags. Specify error responses. Specify version at generation time.
The default error entry is now used to cover all errors, as adding a new error for every possible status code was a bit much. This also properly includes the real error type now!
…rer. Improve the service labels by specifying explicit tags.
Replace Output Only comments with a field behavior annotation in accounts. Mark some fields as required. Add elaborate description for attributes.
Copy parts of the API docs into the description
Unfortunately, while these help with the creating of resources, they still appear required in contexts where they are not, such as when updating a resource.
johanbrandhorst
force-pushed
the
jbrandhorst-api-docs-improvements
branch
from
24e3dbd
to
2c40770
Compare
Dan-Heath
approved these changes
Apr 8, 2024
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 attempts to refactor much of the patterns used in our protobuf documentation to improve the experience of using the API documentation. Among the general changes:
This PR also contains the beginnings of a refactor of all the service files. So far,
account_service.protoandalias_service.proto(and dependencies) have been updated with the following:// Output onlywith the(google.api.field_behavior) = OUTPUT_ONLYannotation option. The old string confused users as it was part of the field descriptionAdd thethis turned out to be the wrong call as it causes confusion when updating a resource.(google.api.field_behavior) = REQUIREDannotation option to fields that are required in requestsAccount->account) in accordance with the Boundary docs style guideattributefields. Previously,attributefields were completely opaque to users. We now have example inputs for attributes.versionfield is not required when creating a resourceI intend to go through the rest of the service files as and when I find time in the next few weeks. If anyone is interested in helping with this effort, please reach out to me 😄.
Reviewers: copy the contents of
controller.swagger.jsonand upload to https://developer.hashicorp.services/open-api-docs-preview to review the look of the changes. Feel free to also try uploading it to https://editor-next.swagger.io/ to compare against a more capable OpenAPIv2 renderer. Note that the developer preview OpenAPI docs page suffers a few issues. If you see anything that isn't already mentioned in the feedback doc, let me know.