OpenAPI structure, it's crucial to display operations before webhooks to ensure logical progression

[DmytroPankratov]

This approach also helps maintain consistency with established API documentation standards and caters to different user experience levels.

Regarding the ReDoc tool, it's essential to adjust the default order since ReDoc initially displays webhooks before operations. Changing the order improves the overall developer experience by adhering to the recommended structure, making the documentation more intuitive, and ensuring seamless integration with other tools and systems.

• Stripe API: Stripe is known for its excellent API documentation, which clearly shows operations before webhooks. The well-organized structure allows developers to find relevant information quickly. Link: https://stripe.com/docs/api

• GitHub API: GitHub's API documentation displays operations first, followed by webhooks, making it easy for developers to explore the API and understand its functionalities. Link: https://docs.github.com/en/rest

• Slack API: The Slack API documentation is another good example of the recommended structure, with operations listed before webhooks, making it intuitive and accessible for developers. Link: https://api.slack.com/apis

• Rebilly https://api-reference.rebilly.com/tag/Payment-instruments

• etc

These examples serve as a reference for creating clear and well-structured OpenAPI documentation that prioritizes operations before webhooks, ensuring an optimal developer experience.

I am using ReDoc in two products.

• https://api-docs.solidgate.com/
• https://api-docs.chargebackhit.com/

We, along with the developers, tried to find a solution to this problem, conducted an analysis, and realized that in this file, it is necessary to change the order of conditions.

https://github.com/Redocly/redoc/blob/main/src/services/MenuBuilder.ts

To display operations before webhooks, you need to swap the following conditions: `if (webhooks) { getTags(parser, webhooks, true); }

if (spec.paths) { getTags(parser, spec.paths); } `

Here's the modified version:

`if (spec.paths) { getTags(parser, spec.paths); }

if (webhooks) { getTags(parser, webhooks, true); } `

By changing the order of these conditions in the file, you ensure that operations are displayed before webhooks, providing a more intuitive and logical structure.

[jeremyfiel]

Please submit a PR with your requested changes and they will be reviewed! Thanks for taking the time to investigate and provide feedback.