[OAS/HTTP] Empty response bodies (status only) and descriptions for responses#188632
Conversation
|
Pinging @elastic/kibana-core (Team:Core) |
| */ | ||
| 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.
| }, | ||
| 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.
| extractVersionedResponses(createTestRoute(), oasConverter, ['application/test+json']) | ||
| ).toEqual({ | ||
| 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: |
…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 |
…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":"jeanlouis.leysens@elastic.co"},"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 <jeanlouis.leysens@elastic.co>
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
{ //... 201: { description: 'Resource created!' } //... }Risks
No notable risks