github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-25 02:09:32 -04:00
Code Issues Projects Releases Packages Wiki Activity
kibana/docs/api-generated
History
Kibana Machine 36dbb40cb6
[8.6] [DOCS] Create open API specification for find rules (#147061) (#147391) 
# Backport

This will backport the following commits from `main` to `8.6`:
- [[DOCS] Create open API specification for find rules
(#147061)](https://github.com/elastic/kibana/pull/147061)

<!--- Backport version: 8.9.7 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2022-12-12T19:36:44Z","message":"[DOCS]
Create open API specification for find rules
(#147061)","sha":"d862f46c2a6930a9f219ec5287dcce7bb286b305","branchLabelMapping":{"^v8.7.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Feature:Alerting","release_note:skip","Team:ResponseOps","docs","v8.7.0","v8.6.1"],"number":147061,"url":"https://github.com/elastic/kibana/pull/147061","mergeCommit":{"message":"[DOCS]
Create open API specification for find rules
(#147061)","sha":"d862f46c2a6930a9f219ec5287dcce7bb286b305"}},"sourceBranch":"main","suggestedTargetBranches":["8.6"],"targetPullRequestStates":[{"branch":"main","label":"v8.7.0","labelRegex":"^v8.7.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/147061","number":147061,"mergeCommit":{"message":"[DOCS]
Create open API specification for find rules
(#147061)","sha":"d862f46c2a6930a9f219ec5287dcce7bb286b305"}},{"branch":"8.6","label":"v8.6.1","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Co-authored-by: Lisa Cawley <lcawley@elastic.co>
2022-12-12 14:21:10 -07:00
..
cases [8.6] [DOCS] Add assignees query parameter to find cases API (#146087) (#146585) 2022-11-29 11:11:22 -07:00
connectors [8.6] Add open API specification for list connector types (#145951) (#146330) 2022-11-24 13:12:06 -07:00
machine-learning [DOCS] Link to open API specification from ML sync API (#142136) 2022-09-29 08:29:07 -07:00
rules [8.6] [DOCS] Create open API specification for find rules (#147061) (#147391) 2022-12-12 14:21:10 -07:00
template [DOCS] Add ML open API output to appendix (#141556) 2022-09-26 11:00:00 -07:00
README.md [8.6] [DOCS] Create open API specification for find rules (#147061) (#147391) 2022-12-12 14:21:10 -07:00

README.md

OpenAPI (Experimental)

Open API specifications (OAS) exist in JSON or YAML format for some Kibana features, though they are experimental and may be incomplete or change later.

A preview of the API specifications can be added to the Kibana Guide by using the following process:

. Install OpenAPI Generator, or a similar tool that can generate HTML output from OAS.

. Optionally validate the specifications by using the commands listed in the appropriate readmes.

. Generate HTML output. For example:

openapi-generator-cli generate -g html -i $GIT_HOME/kibana/x-pack/plugins/alerting/docs/openapi/bundled.yaml -o $GIT_HOME/kibana/docs/api-generated/rules -t $GIT_HOME/kibana/docs/api-generated/template

openapi-generator-cli generate -g html -i $GIT_HOME/kibana/x-pack/plugins/cases/docs/openapi/bundled.yaml -o $GIT_HOME/kibana/docs/api-generated/cases -t $GIT_HOME/kibana/docs/api-generated/template

openapi-generator-cli generate -g html -i $GIT_HOME/kibana/x-pack/plugins/actions/docs/openapi/bundled.yaml -o $GIT_HOME/kibana/docs/api-generated/connectors -t $GIT_HOME/kibana/docs/api-generated/template

openapi-generator-cli generate -g html -i $GIT_HOME/kibana/x-pack/plugins/ml/common/openapi/ml_apis_v3.yaml -o $GIT_HOME/kibana/docs/api-generated/machine-learning -t $GIT_HOME/kibana/docs/api-generated/template

. Rename the output files. For example:

 mv $GIT_HOME/kibana/docs/api-generated/rules/index.html $GIT_HOME/kibana/docs/api-generated/rules/rule-apis-passthru.asciidoc
mv $GIT_HOME/kibana/docs/api-generated/cases/index.html $GIT_HOME/kibana/docs/api-generated/cases/case-apis-passthru.asciidoc
mv $GIT_HOME/kibana/docs/api-generated/connectors/index.html $GIT_HOME/kibana/docs/api-generated/connectors/connector-apis-passthru.asciidoc
mv $GIT_HOME/kibana/docs/api-generated/machine-learning/index.html $GIT_HOME/kibana/docs/api-generated/machine-learning/ml-apis-passthru.adoc

. If you're creating a new set of API output, you will need to have a page that incorporates the output by using passthrough blocks. For more information, refer to Asciidoctor docs

. Verify the output by building the Kibana documentation. At this time, the output is added as a technical preview in the appendix.

Known issues

  • Some OAS 3.0 features such as anyOf, oneOf, and allOf might not display properly in the preview. These are on the Short-term roadmap at this time.