[DOCS] Generate Kibana API docs from open API specifications #137240

lcawl · 2022-07-26T21:12:38Z

Per #82587, it's a long-term plan to automatically generate open API specifications for Kibana.

In the nearer term, there are plans to publish API documentation from such specifications. This is already being done for the Cloud APIs, for example.

To get the docs automation rolling, we can create v3 open API specifications for Kibana and use open source tools to generate interim HTML output for the following APIs:

Get features API [HTTP/OAS] Add description for features API #184248
Kibana spaces APIs [HTTP/OAS] Add descriptions for spaces APIs #184252
Kibana role management APIs [HTTP/OAS] Add descriptions for role management APIs #184265
User session management APIs [HTTP/OAS] Add descriptions for role management APIs #184265
Saved objects APIs [HTTP/OAS] Add tags and summaries for saved object APIs #184184, [OAS] Refresh saved objects API document #186134
- Export objects [OAS] Add saved objects openAPI folder #162522
- Import objects [OAS] Add saved objects openAPI folder #162522
- Resolve import errors [DOCS] Saved objects - resolve import errors API #162825
- Rotate encryption key [DOCS] Saved objects - rotate key API #162566
- Get object - deprecated [OAS] Add deprecated saved object APIs #164355
- Bulk get objects - deprecated [OAS] Add deprecated saved object APIs #164355
- Find objects - deprecated [OAS] Add deprecated saved object APIs #164355
- Create saved objects - deprecated [OAS] Add deprecated saved object APIs #164355
- Bulk create saved objects - deprecated [OAS] Add deprecated saved object APIs #164355
- Update object - deprecated [OAS] Add deprecated saved object APIs #164355
- Bulk update objects - deprecated [OAS] Add deprecated saved object APIs #164355
- Delete object - deprecated [OAS] Add deprecated saved object APIs #164355
- Bulk delete objects - deprecated [OAS] Add deprecated saved object APIs #164355
- Resolve object - deprecated [OAS] Add deprecated saved object APIs #164355
- Bulk resolve objects - deprecated [OAS] Add deprecated saved object APIs #164355
Data views APIs [HTTP/OAS] Add descriptions for data view APIs #184182
- Get all data views [OAS] Add data views openAPI folder and first entrypoints #163444
- Get data view [OAS] Add data views openAPI folder and first entrypoints #163444
- Create data view [OAS] Add data views openAPI folder and first entrypoints #163444
- Update data view [OAS] Add data views openAPI folder and first entrypoints #163444
- Delete data view [OAS] Add data views openAPI folder and first entrypoints #163444
- Get default data view [OAS] Add data views openAPI folder and first entrypoints #163444
- Set default data view [OAS] Add data views openAPI folder and first entrypoints #163444
- Update data view fields metadata [OAS] Data views update fields meta spec files. #164547
- Get runtime field [OAS] Add data views openAPI folder and first entrypoints #163444
- Create runtime field [OAS] Create runtime field API #163776
- Upsert runtime field [OAS] Create runtime field API #163776
- Update runtime field [OAS] Adding update and delete to runtime fields OAS #163777
- Delete runtime field [OAS] Adding update and delete to runtime fields OAS #163777
- Swap references [DOCS][OAS] Add data view swap saved object references and preview APIs #187927
- Swap references preview [DOCS][OAS] Add data view swap saved object references and preview APIs #187927
Index patterns APIs [Docs] Add OpenAPI spec for dataviews #161279
Alerting APIs [HTTP] Make alerting APIs public #183945, [HTTP/OAS] Add description in create rule request body #183564
- Create rule [DOCS] Create open API specification for create rule #149565
- Delete rule [DOCS] Create open API specification for update/get/delete rule #147407
- Disable rule [DOCS] Create open API specification for disable/enable rule and mute/unmute all alerts #148360 #148494
- Enable rule [DOCS] Create open API specification for disable/enable rule and mute/unmute all alerts #148360 #148494
- Find rules [DOCS] Create open API specification for find rules #147061
- Get alerting framework health [DOCS] Create OAS for get rule types and get alerting framework health #148774
- Get rule [DOCS] Create open API specification for update/get/delete rule #147407
- Get rule types [DOCS] Create OAS for get rule types and get alerting framework health #148774
- Update rule [DOCS] Create open API specification for update/get/delete rule #147407
- Mute all alerts [DOCS] Create open API specification for disable/enable rule and mute/unmute all alerts #148360 #148494
- Mute alert [DOCS] Create open API specification for disable/enable rule and mute/unmute all alerts #148360 #148494
- Unmute all alerts [DOCS] Create open API specification for disable/enable rule and mute/unmute all alerts #148360 #148494
- Unmute alert [DOCS] Create open API specification for disable/enable rule and mute/unmute all alerts #148360 #148494
- Deprecated APIs [DOCS] Add specifications for deprecated alert APIs #149655
Action and connector APIs [HTTP] Make connector APIs public #184068, [DOCS][OAS] Add descriptions, tags, deprecation to connector APIs #184956
- Create connector [DOCS] Create open API specification for create/update connector #148691
- Delete connector [DOCS] Create open API specification for delete/get connectors #148360
- Get connector [DOCS] Create open API specification for delete/get connectors #148360
- Get all connectors [DOCS] Create open API specification for delete/get connectors #148360
- List all connector types Add open API specification for list connector types #145951
- Run connector [DOCS] Create open API specification for run connector #149274
- Update connector [DOCS] Create open API specification for create/update connector #148691
- Deprecated connector APIs [DOCS] Add specifications for deprecated connector APIs #149637
Cases APIs [HTTP] Make case APIs public #184074
- Add comment [DOCS] Automate output for 4 case APIs #142173
- Create case [DOCS] Automate docs for create/update/delete case APIs #142929
- Delete cases [DOCS] Automate docs for create/update/delete case APIs #142929
- Delete comments [DOCS] Automate output for 4 case APIs #142173
- Find cases [DOCS] Automate final case APIs #145007
- Find connectors [DOCS] Automate final case APIs #145007
- Get alerts [DOCS] Automate final case APIs #145007
- Get case activity [DOCS] Automate final case APIs #145007
- Get case [DOCS] Automate docs for get case APIs #144950
- Get case status [DOCS] Automate docs for get case APIs #144950
- Get cases by alert [DOCS] Automate docs for get case APIs #144950
- Get comments [DOCS] Automate output for 4 case APIs #142173, [DOCS] Automate docs for get case APIs #144950
- Get configuration [DOCS] Automate docs for push case and case case config APIs #144657, [DOCS] Automate docs for get case APIs #144950
- Get reporters [DOCS] Automate docs for get case APIs #144950
- Get tags [DOCS] Automate docs for get case APIs #144950
- Push case [DOCS] Automate docs for push case and case case config APIs #144657
- Set configuration [DOCS] Automate docs for push case and case case config APIs #144657
- Update cases [DOCS] Automate docs for create/update/delete case APIs #142929
- Update comment [DOCS] Automate output for 4 case APIs #142173
- Update configuration [DOCS] Automate docs for push case and case case config APIs #144657
Import and export dashboard APIs
Logstash configuration management APIs [HTTP/OAS] Add descriptions for Logstash pipeline APIs #184266
Machine learning APIs Add v2 open API spec for ml sync #136234, [DOCS] Add v3 open API spec for ml sync #141554, [HTTP/OAS] Add ML sync API description #184154
Short URLs APIs [HTTP/OAS] Add descriptions for short URL APIs #184267
Task manager APIs [HTTP/OAS] Add description for task manager health API #184249
Upgrade assistant APIs [HTTP/OAS] Add descriptions for upgrade assistant APIs #184269
Detection APIs see also https://github.com/elastic/examples/blob/master/Security%20Analytics/SIEM-examples/Detections-API/Kibana.postman_collection.v2.json
- Create rule
- Get rule
- Find rules
- Update rule
- Delete rule
- Bulk create rule actions
- Bulk delete rule actions
- Bulk update rule actions
- Bulk action
- Get index
- Delete index
- Get tags
- Import rules
- Export rules
- Get privileges
- Get signal alerts
- Set signal alert status
- Load prebuilt rules
- Get prebuilt rule status
Exception APIs
List APIs
Detection alerts migration APIs
Timeline APIs
Endpoint management APIs

The text was updated successfully, but these errors were encountered:

elasticmachine · 2022-07-26T21:12:40Z

Pinging @elastic/kibana-docs (Team:Docs)

Relates to #137240

nicholas-r-king · 2023-05-24T23:51:28Z

Any timeline on data-views API open API specification. This would be useful for the terraform provider.

This PR drafts openAPI specifications for: - [Create runtime field API](https://www.elastic.co/guide/en/kibana/master/data-views-runtime-field-api-create.html). - [Upsert runtime field API](https://www.elastic.co/guide/en/kibana/master/data-views-runtime-field-api-upsert.html) Relates to #137240

This PR drafts openAPI specifications for: - [Create runtime field API](https://www.elastic.co/guide/en/kibana/master/data-views-runtime-field-api-create.html). - [Upsert runtime field API](https://www.elastic.co/guide/en/kibana/master/data-views-runtime-field-api-upsert.html) Relates to elastic#137240

This PR drafts openAPI specifications for: - [Delete runtime field API](https://www.elastic.co/guide/en/kibana/master/data-views-runtime-field-api-delete.html). - [Update runtime field API](https://www.elastic.co/guide/en/kibana/master/data-views-runtime-field-api-update.html) Relates to #137240

This PR drafts openAPI specifications for: - [Create runtime field API](https://www.elastic.co/guide/en/kibana/master/data-views-runtime-field-api-create.html). - [Upsert runtime field API](https://www.elastic.co/guide/en/kibana/master/data-views-runtime-field-api-upsert.html) Relates to #137240

## Summary Relates to #137240 This PR aims to draft openAPI specifications for [Resolve import errors API](https://www.elastic.co/guide/en/kibana/current/saved-objects-api-resolve-import-errors.html). --------- Co-authored-by: Alejandro Fernández Haro <afharo@gmail.com> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>

lcawl added Team:Docs docs labels Jul 26, 2022

lcawl self-assigned this Jul 26, 2022

lcawl mentioned this issue Jul 29, 2022

[DOCS] Add v2 open API spec for cases #137618

Closed

lcawl mentioned this issue Oct 7, 2022

[DOCS] Automate docs for create/update/delete case APIs #142929

Merged

This was referenced Nov 5, 2022

[DOCS] Automate docs for push case and case case config APIs #144657

Merged

[DOCS] Automate docs for get case APIs #144950

Merged

[DOCS] Automate final case APIs #145007

Merged

lcawl added a commit that referenced this issue Nov 17, 2022

Update CODEOWNERS

7740b7b

Relates to #137240

lcawl mentioned this issue Nov 17, 2022

Update CODEOWNERS #145606

Merged

kpollich mentioned this issue Nov 21, 2022

[Fleet] Prepare Fleet API for promotion to GA #123150

Closed

21 tasks

lcawl mentioned this issue Nov 22, 2022

Add open API specification for list connector types #145951

Merged

This was referenced Dec 6, 2022

[DOCS] Create open API specification for find rules #147061

Merged

[DOCS] Create open API specification for update/get/delete rule #147407

Merged

This was referenced Jan 12, 2023

[DOCS] Create OAS for get rule types and get alerting framework health #148774

Merged

[DOCS] Add 401 responses to case API specifications #148857

Merged

This was referenced Jan 20, 2023

[DOCS] Create open API specification for run connector #149274

Merged

[DOCS] Create open API specification for create rule #149565

Merged

This was referenced Jan 26, 2023

[DOCS] Add specifications for deprecated connector APIs #149637

Merged

[DOCS] Add specifications for deprecated alert APIs #149655

Merged

lcawl mentioned this issue Feb 22, 2023

Bulk actions have been updated over time to have more capabilities, docs still have a select few. elastic/security-docs#3004

Closed

lcawl mentioned this issue Jul 13, 2023

Remove mlr-docs codeowner for OAS #161820

Merged

lcawl mentioned this issue Jul 25, 2023

[OAS] Add saved objects openAPI folder #162522

Merged

This was referenced Jul 26, 2023

[DOCS] Saved objects - rotate key API #162566

Merged

[DOCS] Saved objects - resolve import errors API #162825

Merged

lcawl mentioned this issue Aug 8, 2023

[OAS] Add data views openAPI folder and first entrypoints #163444

Merged

This was referenced Aug 14, 2023

[OAS] Create runtime field API #163776

Merged

[OAS] Adding update and delete to runtime fields OAS #163777

Merged

lcawl mentioned this issue Aug 21, 2023

[OAS] Add deprecated saved object APIs #164355

Merged

amyjtechwriter mentioned this issue Aug 23, 2023

[OAS] Data views update fields meta spec files. #164547

Merged

This was referenced May 22, 2024

[HTTP] Make connector APIs public #184068

Merged

[HTTP] Make case APIs public #184074

Merged

lcawl mentioned this issue Jul 9, 2024

[DOCS][OAS] Add data view swap saved object references and preview APIs #187927

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS] Generate Kibana API docs from open API specifications #137240

[DOCS] Generate Kibana API docs from open API specifications #137240

lcawl commented Jul 26, 2022 •

edited

Loading

elasticmachine commented Jul 26, 2022

nicholas-r-king commented May 24, 2023

[DOCS] Generate Kibana API docs from open API specifications #137240

[DOCS] Generate Kibana API docs from open API specifications #137240

Comments

lcawl commented Jul 26, 2022 • edited Loading

elasticmachine commented Jul 26, 2022

nicholas-r-king commented May 24, 2023

lcawl commented Jul 26, 2022 •

edited

Loading