[DOCS] Automate output for 4 case APIs #142173
Conversation
lcawl
added
release_note:skip
|
Documentation preview: |
|
Pinging @elastic/response-ops (Team:ResponseOps) |
|
Pinging @elastic/response-ops-cases (Feature:Cases) |
x-pack/plugins/cases/docs/openapi/components/examples/update_comment_response.yaml
Show resolved
Hide resolved
| @@ -0,0 +1,9 @@ | |||
| title: Add case comment request | |||
There was a problem hiding this comment.
There are a few other comment types that we support:
I can help add those later if that's easier though.
There was a problem hiding this comment.
Thanks! If you're okay with deferring that work to a subsequent PR, we can get this initial set of content added then augment from there. I'll definitely take you up on the offer for help to understand what those other types accomplish.
x-pack/plugins/cases/docs/openapi/components/schemas/alert_indices.yaml
Outdated
Show resolved
Hide resolved
x-pack/plugins/cases/docs/openapi/components/schemas/case_response_closed_by_properties.yaml
Outdated
Show resolved
Hide resolved
x-pack/plugins/cases/docs/openapi/components/schemas/case_response_updated_by_properties.yaml
Show resolved
Hide resolved
| - url: 'http://localhost:5601' | ||
| description: local | ||
| paths: | ||
| # '/s/{spaceId}/api/cases': |
There was a problem hiding this comment.
Should we remove these commented out lines?
There was a problem hiding this comment.
Since I'm just using these -min. files until I get all the automated docs generated, I think it's okay to leave this as-is until we delete it.
💚 Build Succeeded
Metrics [docs]
History
To update your PR or re-run it, just comment with: |
💚 All backports created successfully
Note: Successful backport PRs will be merged automatically after passing CI. Questions ?Please refer to the Backport tool documentation |
(cherry picked from commit 2d8b29e)
Summary
Relates to #137240
This PR uses the open API v3 specification (OAS) to generate output for some case APIs. It takes output from the open-api generator, in particular the HTML generator, applies a custom template and uses that output in a passthrough block in an appendix in the Kibana Guide. I've created a temporary
bundled-min.jsonso that we can incrementally publish the previews without ill-affecting the spec.Some elective changes were made in the specifications to improve the output, for example:
. Added titles so that the "models" in the output have clearer labels
. Added missing "required" and "nullable" properties
. Segmented the specifications into smaller chunks in the "schemas" folder, so they're easier to re-use
A note is also added to the original API pages to link to (1) the OAS as the source of truth, and (2) the generated output for a preview.
Note: The "oneOf" feature (where you can update either an alert or a comment in a case, for example) does not show up perfectly in the output. The two options are there in the model listings, but they're not linked. I've added this to the list of outstanding improvements necessary if we stay with this longer-term.