Reordering how endpoints appear in an OpenAPI specification without reordering the endpoints

Say you have a Swagger or OpenAPI specification like so: openapi: 3.0.3 info: title: foobar version: 1.0.0 paths: /foo: get: tags: - foo responses: '200': description: Success /bar: get: tags: - bar responses: '200': description: Success

If you wanted to update your documentation so that /bar appeared first before /foo, the easy and obvious solution would be to just copy and paste the /bar section above /foo like so:

However, this might not be desirable, either because its a lot of copy and pasting or because the specification is being autogenerated and you can't change easily the order in which its put together.

But did you know that the order in which endpoints appear in the specification can also be determined by the order of the tags within the top level tags object? Thus, an alternative way to update the documentation would be like so:

In this case, /bar will the shown first before /foo even though it is the second path being declared. Pretty neat. You can play around with this more in the Swagger Editor.