search

Redocly / redoc

📘 OpenAPI/Swagger-generated API Reference Documentation
https://redocly.github.io/redoc/
MIT License
23.46k stars 2.29k forks source link

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

Open dougbreaux opened 3 years ago

dougbreaux commented 3 years ago

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 : image

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 commented 11 months ago

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 commented 11 months ago

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

lornajane commented 11 months ago

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

BernhardBln commented 10 months ago

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 commented 8 months ago

Quick poke on this item

fstubner commented 7 months ago

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 commented 2 months ago

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 commented 2 months ago

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!