[Kibana Docs] Broken link on Kibana Fleet APIs documentation
Closed this issue · 5 comments
Hello,
In the Kibana Fleet APIs documentation there is a link to the spec file of the Fleet API, but this link is now broken, it leads to a non existent file on the Kibana repository.
This is the link: https://github.com/elastic/kibana/blob/main/x-pack/plugins/fleet/common/openapi/bundled.json
It seems that the only file in this path is now the README.md file.
Pinging @elastic/fleet (Team:Fleet)
Great catch and thank you for filing this @leandrojmp - I've transferred this to our docs repo.
cc @kilfoyle - Looks like we broke this link when we swapped around some of the OpenAPI code gen stuff 😶. Would you be able to help with fixing this?
@lcawl Now that we have published, generated API docs 🎉 , would you be able to point me to the Fleet API docs and also the spec? I'll update the links in the Kibana Fleet APIs page, shown below:
Kibana Fleet APIs
You can find details for all available Fleet API endpoints in our generated Fleet API docs. This documentation is experimental and may be incomplete or change later.
The main source of truth for the Fleet API can be found in the self-contained spec file that you can use to generate docs using Swagger or a similar tool. For more information, refer to the Fleet OpenAPI readme.
In this section, we provide examples of some commonly used Fleet APIs.
@lcawl Now that we have published, generated API docs 🎉 , would you be able to point me to the Fleet API docs and also the spec?
Since there are multiple groupings of Fleet APIs, it's simplest to just point to "...the generated {api-kibana}[Kibana API docs]".
The use of the api-kibana attribute ensures it uses the appropriate version branch in that site.
Per elastic/kibana#194788 there isn't a self-contained spec file specifically for Fleet anymore--they're included in the generated file alongside more and more other APIs. Technically you could point to https://github.com/elastic/kibana/blob/main/oas_docs/bundle.json, but that file doesn't have all the extra bits we add via overlays and IMO that paragraph should just be omitted from the docs. In fact, I think it would be worth pondering what's worth keeping in this entire page. The "to save time..." tidbits look worth keeping, but technically we could move those over to the API docs too (e.g. you can all all sorts of info like that to the tag descriptions, as we did for cases, for example: https://www.elastic.co/docs/api/doc/kibana/group/endpoint-cases. If you want to discuss further, lmk!
The new Fleet API docs are included in the Kibana API docs here: https://www.elastic.co/docs/api/doc/kibana