Generated OpenAPI introduction pages lack information #3721
Labels
component:docs
Documentation improvements, including new or updated content
dx
Documentation infrastructure typically handled by the Camunda DX team
theme:api-streamline
Issues related to the theme of streamlining APIs
Related to, possibly encapsulating, #3585.
The "Introduction" page of each generated API Explorer (example) is light on information, and it can seem like a dead-end if the reader doesn't see the sidebar navigation for endpoints.
See more discussion in https://camunda.slack.com/archives/C026U8GBNSW/p1713806109791589.
The work
Tasks
Implementation notes
One idea is to add an index of endpoints to the Introduction pages.
There is useful information on the pages, like authentication schema and license/contact information, so we might not want to delete the page completely. See the generator code itself for possible inspiration on how we could encapsulate it, and add logic on top that generates some sort of index of endpoints. It might still be a post-generation script to add the index of endpoints to the introduction page itself.
On the other hand, there is no obvious hook for customizing the Introduction page, and it may prove to be a large effort to introduce an index of endpoints.
The text was updated successfully, but these errors were encountered: