search

elastic / kibana

Your window into the Elastic Stack
https://www.elastic.co/products/kibana
Other
19.71k stars 8.13k forks source link

Kibana Fleet API docs need improvement #190402

Open nerophon opened 1 month ago

nerophon commented 1 month ago

Kibana version: 8.14

The documentation of the Kibana Fleet API needs significant improvement. There is an introduction here: https://www.elastic.co/guide/en/fleet/current/fleet-apis.html

Then the API can be viewed in various ways, two examples: https://www.elastic.co/guide/en/fleet/current/fleet-apis.html https://petstore.swagger.io/?url=https://raw.githubusercontent.com/elastic/kibana/master/x-pack/plugins/fleet/common/openapi/bundled.json#/

What this documentation lacks is any explanation or context around why they may be used, and what they are useful for. Starting from a user's perspective, we may for example wish to query which integration packages are presently installed, and if necessary install them. But nowhere is there an explanation of which series of APIs would be required to be called to achieve that.

Arguably, use-cases could be deduced if the descriptions of the APIs were thorough; but instead they are threadbare, generally providing no further information than the name of the API itself suggests. What is needed is a full explanation of the concepts involved, how these APIs interact, and much fuller descriptions of each call.

elasticmachine commented 1 month ago

Pinging @elastic/fleet (Feature:Fleet)

elasticmachine commented 1 month ago

Pinging @elastic/fleet (Team:Fleet)

kpollich commented 1 month ago

Hi @nerophon, thanks for opening this issue. There's a few things to make clear for context here:

  1. Fleet's API documentation is manually authored today using the OpenAPI spec. The source files for the documentation live here: https://github.com/elastic/kibana/tree/main/x-pack/plugins/fleet/common/openapi. The reason we can view it in multiple places is because these places simply consume the bundled.json/yaml file provided here and present it via a dynamically generated UI.
  2. https://www.elastic.co/guide/en/fleet/current/fleet-apis.html is an experimental implementation of rendering OpenAPI specs directly in Elastic's first-party documentation system. It hasn't been iterated on much since its inception, and the documentation engineering team has been working on a replacement implementation using alternate services.
  3. Kibana has been rolling out its own code generation pipeline for OpenAPI specs here: https://github.com/elastic/kibana/issues/180056. This would replace Fleet's manual authoring process, instead relying on hints/config directly in code alongside our API route declarations. We have https://github.com/elastic/kibana/issues/184685 on the Fleet side that tracks our adoption of this pattern. We won't make any changes to the existing OpenAPI specs today in favor of adopting the code gen pipeline first.

I am in full agreement that some more context around Fleet's APIs would be helpful, and I do think some "recipe" style documentation with common use cases would be a great way to improve the documentation here.

Starting from a user's perspective, we may for example wish to query which integration packages are presently installed, and if necessary install them. But nowhere is there an explanation of which series of APIs would be required to be called to achieve that.

Is this a problem that is best solved by API documentation, or by higher level explanations of Fleet's data models, relationships, etc? I'm wondering if we should solve this problem at a higher level instead of sort of building a better mental model around Fleet's data model starting at its REST API.

Arguably, use-cases could be deduced if the descriptions of the APIs were thorough; but instead they are threadbare, generally providing no further information than the name of the API itself suggests.

Improving description is an obvious win here, and this will be top of mind as we get started on https://github.com/elastic/kibana/issues/184685 above. This will also become more urgent as our new implementation of hosted API docs is rolled out. Serverless API docs are already in the process of being moved over to a new tool that's not publicly shareable yet. Check out some of the recent documentation team update emails for some more info.