feat(http): support inline documentation comments for response descriptions #9254
+913
−20
Conversation
This file contains hidden or 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
- give meaning to inline block comment in response description
Hajime-san
requested review from
AlitzelMendez,
bterlson,
chrisradek,
markcowl,
timotheeguerin and
witemple-msft
as code owners
Author
|
@microsoft-github-policy-service agree |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
I think this proposal #8148 is an effective approach for concisely and flexibly defining response descriptions in OpenAPI documents from TypeSpecs.
It also mentions that inline decorators are not syntactically valid. While it is possible to implement that, the tradeoff with complexity is that inline doc comments are sufficient.
closes #8148
Changes
To achieve this functionality, I made the following changes:
compilerhttpcompiler/formatterwebsitePlease let me know if I've missed any, as I think it covers most use cases.
Associating inline doc comments in
tsp-openapi3will also make it easier to migrate from OpenAPI documents.The feature itself doesn't require much code, but it would be numerous changes to test code, so I haven't included it in this PR.
If the team finds this feature useful, I will consider submitting it as a separate PR.