Prominently display the Operation name in the main document area (and sidebar)

[dougbreaux]

Describe the problem to be solved I find it unhelpful that the individual operation names are not prominently displayed in the main documentation area. I expect them both in the navigation sidebar (like #753) and in the main pane

Describe the solution you'd like e.g. right here in this whitespace, I want the operation name :

Describe alternatives you've considered Considered renaming the "Summary" to be the path, or using a different tool.

Additional context I initially made this request against Apicurio Studio: https://github.com/Apicurio/apicurio-studio/issues/1608. I also see this issue is partially related: https://github.com/Redocly/redoc/issues/753

[lornajane]

I'm sorry that you find it unhelpful, but I think this is the expected behaviour. The OperationIDs are mostly used in programming contexts, and so we don't display them to users. Instead we use the short operation information from the summary field, and have no plans to change that in Redoc itself. I think your best option would be to update the summary fields before publishing the documentation to achieve what you describe.

[dougbreaux]

But... but... this is API docs for programming to. 🤷

[lornajane]

I'm still thinking about this one, and now I think we should leave it open for more comment/consideration.

[BernhardBln]

I think it would already be helpful to leave the default as it is, but provide an option to switch for operationIds. People tend to write whole sentences into the summary field, which renders the docs unreadable...

[dougbreaux]

Quick poke on this item

[fstubner]

I am currently trying to implement redoc and also have this challenge and was looking for a way to display the operationIds over the description.

[shudac]

This is a documentation tool. There is an utter need for a programmer implementing api to know operationId, so yeah, let's argue years and years that this is the more valuable information for programmer then summary or description and let's not put it over there for a programmer to see. Let's instruct newbie that there is that great documentation tool displaying all he needs to know about an api, just not the operationId. So he can open a JSON file and dig it over there. Just for the heck of it. Because the expected behaviour is to hide that useful information from the programmer, because it is a programming context, which he should build, so let's keep operationId better buried up deep in JSON somewhere. Let's complicate the things... Because it is so tough to display operationId between summary and description somewhere... And yeah let's wait another 3 years to think about usefulness of this information for somebody, because why not...

[lornajane]

I've locked the issue for further conversation since the discussion does not seem to be constructive. The issue remains open and under consideration though!