Routes sorting in OpenAPI documentation

[Venerons]

Is there a way to define the sorting order of the routes in the generated OpenAPI documentation?

Right now, I don't understand what order are the routes sorted in the documentation. It is consistent (so not random) but I have not found what actually affects the sorting. The routes are not shown in the same order they are registered via huma.Register, the OperationID doesn't seem to matter, and neither the Path or Method.

Does anyone know how it sort it internally, or even better if there is a way to actually define it?

[danielgtaylor]

I believe you can use the OpenAPI tags for this. For each operation you can add a tag like:

huma.Register(api, huma.Operation{
	// ...
 	Tags: []string{"Something"}
}, /* ... */)

Then on the OpenAPI object you can set the order the tags should appear and give them descriptions:

api.OpenAPI().Tags = []*huma.Tag{
	{Name: "Something", Description: "Some description"},
	{Name: "Another Thing", Description: "Some other description"},
	// ...
}

This behavior depends on the documentation tool you use, but I think most of them do this. Hope this helps!

FYI, the paths and operations are a JSON object (map) so they are unordered by definition. The tags let you provide an order because lists are ordered. This is just the way OpenAPI is designed, which has this con but also pros like it being impossible to accidentally create two different GET operations on the same URL path.