Skip to content

[OAS/HTTP] Empty response bodies (status only) and descriptions for responses#188632

Merged
jloleysens merged 13 commits intoelastic:mainfrom
jloleysens:oas-http/support-empty-response-bodies
Jul 22, 2024
Merged

[OAS/HTTP] Empty response bodies (status only) and descriptions for responses#188632
jloleysens merged 13 commits intoelastic:mainfrom
jloleysens:oas-http/support-empty-response-bodies

Conversation

@jloleysens
Copy link
Copy Markdown
Contributor

@jloleysens jloleysens commented Jul 18, 2024

Summary

  • Adds the ability to exclude a response schema when declaring route schemas
  • Adds the ability to provide a description of a the response

See code comments for more info.

Example

You can declare a response with no validation to imply an empty object in OAS

router.versioned.post({ version: '2023-10-31', access: 'public', path: '...' })
  .addVersion({
    validation: {
      responses: {
        201: { description: 'Resource created!' }
      }
    }
  }, () => {})

Will result in

{
 //...
  201: { description: 'Resource created!' }
 //...
}

Risks

No notable risks

@jloleysens jloleysens added Feature:http Team:Core Platform Core services: plugins, logging, config, saved objects, http, ES client, i18n, etc t// release_note:skip Skip the PR/issue when compiling release notes Feature:OAS Work or issues related to Core-provided mechanisms for generating OAS v8.16.0 labels Jul 18, 2024
@jloleysens jloleysens requested a review from a team as a code owner July 18, 2024 10:47
@elasticmachine
Copy link
Copy Markdown
Contributor

Pinging @elastic/kibana-core (Team:Core)

*/
bodyContentType?: string;
body: LazyValidator;
body?: LazyValidator;
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.',
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@elasticmachine
Copy link
Copy Markdown
Contributor

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

  • [job] [logs] Jest Tests #6 / SearchBar renders the search box

Metrics [docs]

✅ unchanged

@kibana-ci
Copy link
Copy Markdown

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

  • [job] [logs] FTR Configs #24 / security app - login selector Basic functionality can login anonymously preserving original URL
  • [job] [logs] Jest Tests #1 / Severity form field renders

Metrics [docs]

✅ unchanged

History

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

Copy link
Copy Markdown
Member

@afharo afharo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@jloleysens jloleysens merged commit a8091ab into elastic:main Jul 22, 2024
@kibanamachine kibanamachine added the backport:skip This PR does not require backporting label Jul 22, 2024
@jloleysens jloleysens deleted the oas-http/support-empty-response-bodies branch July 22, 2024 13:29
@lcawl
Copy link
Copy Markdown
Member

lcawl commented Aug 14, 2024

💚 All backports created successfully

Status Branch Result
8.15

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":"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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backport:skip This PR does not require backporting Feature:http Feature:OAS Work or issues related to Core-provided mechanisms for generating OAS release_note:skip Skip the PR/issue when compiling release notes Team:Core Platform Core services: plugins, logging, config, saved objects, http, ES client, i18n, etc t// v8.15.0 v8.15.1 v8.16.0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants