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
- [ ] Figure out how we're going to address this issue
- [ ] Apply to Tasklist REST API
- [ ] Apply to Operate API
- [ ] 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.

[akeller]

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.

Is there a way to do a small spike for this to get a little bit better understanding of effort here?

I ask for two reasons:

• Is it really a concern or problem for our users? Do they navigate through the API docs and this page? (we should see this in Google Analytics)
  • If yes, let's look into how to improve this, specifically looking into the future and thinking about the unified REST API
• If we defer this, how difficult would it be to accept this "risk"? - The information is still available, but just not in the intro page, so we don't recommend linking to it directly. (With this as a public issue, we have something to point to and document any increase in priority/urgency.)

[pepopowitz]

I don't personally believe it's that much of a problem. It's been raised two times, both internally. We could improve the experience...but I don't think it's causing anyone to get stuck. I have not looked at Google Analytics to prove that, though.

There is definitely a spike we could do...but again, if it's not a problem, is it even worth a spike?

[akeller]

Based on your initial sentence here and my gut feeling, let's keep this paused for now. Can you adjust this issue and where it sits on the DevEx board to indicate that it won't be worked on anytime soon?