[OAS/HTTP] Empty response bodies (status only) and descriptions for responses #188632
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
jloleysens
added
Feature:http
Team:Core
|
Pinging @elastic/kibana-core (Team:Core) |
jloleysens
commented
Jul 18, 2024
| /** | ||
| * A string representing the mime type of the response body. | ||
| */ | ||
| bodyContentType?: string; | ||
| body: LazyValidator; | ||
| body?: LazyValidator; |
There was a problem hiding this comment.
This is what caused the need for a number of changes (similar for versioning router). The possibility of having empty response schemas was overlooked in the initial implementation. You might have, for example:
DELETE /api/my-resource
That responds with OK 201 and an empty body. This enables use to represent this in code and OAS.
| @@ -119,9 +119,11 @@ export const registerStatusRoute = ({ | |||
| }, | |||
| response: { | |||
| 200: { | |||
| description: 'Overall status is OK and Kibana should be functioning normally.', | |||
There was a problem hiding this comment.
Added missing body descriptions for the status endpoint.
| 200: { | ||
| description: 'OK response 2023-10-31\nOK response 2024-12-31', // merge multiple version descriptions |
There was a problem hiding this comment.
For versioned endpoints with more than one version (none right now) we will merge their descriptions instead of letting the last version win. Open to different approaches here.
💛 Build succeeded, but was flaky
Failed CI StepsTest FailuresMetrics [docs]
|
💛 Build succeeded, but was flaky
Failed CI StepsTest Failures
Metrics [docs]
History
To update your PR or re-run it, just comment with: |
lcawl
pushed a commit
to lcawl/kibana
that referenced
this pull request
Aug 14, 2024
…esponses (elastic#188632) (cherry picked from commit a8091ab)
💚 All backports created successfully
Note: Successful backport PRs will be merged automatically after passing CI. Questions ?Please refer to the Backport tool documentation |
lcawl
added a commit
that referenced
this pull request
Aug 15, 2024
…s for responses (#188632) (#190545) # Backport This will backport the following commits from `main` to `8.15`: - [[OAS/HTTP] Empty response bodies (status only) and descriptions for responses (#188632)](#188632) <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Jean-Louis Leysens","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-07-22T13:29:15Z","message":"[OAS/HTTP] Empty response bodies (status only) and descriptions for responses (#188632)\n\n## Summary\r\n\r\n* Adds the ability to exclude a response schema when declaring route\r\nschemas\r\n* Adds the ability to provide a description of a the response\r\n\r\nSee code comments for more info.\r\n\r\n## Example\r\n\r\nYou can declare a response with no validation to imply an empty object\r\nin OAS\r\n\r\n```\r\nrouter.versioned.post({ version: '2023-10-31', access: 'public', path: '...' })\r\n .addVersion({\r\n validation: {\r\n responses: {\r\n 201: { description: 'Resource created!' }\r\n }\r\n }\r\n }, () => {})\r\n```\r\n\r\nWill result in\r\n\r\n```jsonc\r\n{\r\n //...\r\n 201: { description: 'Resource created!' }\r\n //...\r\n}\r\n```\r\n\r\n## Risks\r\n\r\nNo notable risks","sha":"a8091ab0acff6f8fae2cbe19c273048fb2734632","branchLabelMapping":{"^v8.16.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Feature:http","Team:Core","release_note:skip","backport:skip","v8.15.0","Feature:OAS","v8.16.0"],"number":188632,"url":"https://github.com/elastic/kibana/pull/188632","mergeCommit":{"message":"[OAS/HTTP] Empty response bodies (status only) and descriptions for responses (#188632)\n\n## Summary\r\n\r\n* Adds the ability to exclude a response schema when declaring route\r\nschemas\r\n* Adds the ability to provide a description of a the response\r\n\r\nSee code comments for more info.\r\n\r\n## Example\r\n\r\nYou can declare a response with no validation to imply an empty object\r\nin OAS\r\n\r\n```\r\nrouter.versioned.post({ version: '2023-10-31', access: 'public', path: '...' })\r\n .addVersion({\r\n validation: {\r\n responses: {\r\n 201: { description: 'Resource created!' }\r\n }\r\n }\r\n }, () => {})\r\n```\r\n\r\nWill result in\r\n\r\n```jsonc\r\n{\r\n //...\r\n 201: { description: 'Resource created!' }\r\n //...\r\n}\r\n```\r\n\r\n## Risks\r\n\r\nNo notable risks","sha":"a8091ab0acff6f8fae2cbe19c273048fb2734632"}},"sourceBranch":"main","suggestedTargetBranches":["8.15"],"targetPullRequestStates":[{"branch":"8.15","label":"v8.15.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v8.16.0","labelRegex":"^v8.16.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/188632","number":188632,"mergeCommit":{"message":"[OAS/HTTP] Empty response bodies (status only) and descriptions for responses (#188632)\n\n## Summary\r\n\r\n* Adds the ability to exclude a response schema when declaring route\r\nschemas\r\n* Adds the ability to provide a description of a the response\r\n\r\nSee code comments for more info.\r\n\r\n## Example\r\n\r\nYou can declare a response with no validation to imply an empty object\r\nin OAS\r\n\r\n```\r\nrouter.versioned.post({ version: '2023-10-31', access: 'public', path: '...' })\r\n .addVersion({\r\n validation: {\r\n responses: {\r\n 201: { description: 'Resource created!' }\r\n }\r\n }\r\n }, () => {})\r\n```\r\n\r\nWill result in\r\n\r\n```jsonc\r\n{\r\n //...\r\n 201: { description: 'Resource created!' }\r\n //...\r\n}\r\n```\r\n\r\n## Risks\r\n\r\nNo notable risks","sha":"a8091ab0acff6f8fae2cbe19c273048fb2734632"}}]}] BACKPORT--> Co-authored-by: Jean-Louis Leysens <[email protected]>
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.
Summary
See code comments for more info.
Example
You can declare a response with no validation to imply an empty object in OAS
Will result in
Risks
No notable risks