Generated OpenAPI introduction pages lack information

[pepopowitz]

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

Beta Give feedback

1. Figure out how we're going to address this issue
2. Apply to Tasklist REST API
3. Apply to Operate API
4. Apply to Zeebe REST API

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.