Tags are sorted in 'random' order in OpenAPI.

[bmeesters]

Currently the endpoints documentation contains a map of tag name to PathItem:

final class OpenApi private (
    val info: Info,
    val paths: Map[String, PathItem],    // <----
    val components: Components
)

Since this uses a map underneath the tags appear random in the resulting openAPI (see for example https://otm5.opentripmodel.org/, which is btw a nice example of what endpoints4s can achieve!). This order also changes if a new tag is added since Maps are unordered in their keys.

I think it would be quite nice if we can sort the keys, for example alphabetically, so it looks a little more tight. I would also be willing to implement this feature myself.

My suggestion would be to add an optional 'sorting' to the OpenApi class that is used when present.

[julienrf]

I wonder if this is more the responsibility of the OpenAPI UI generator instead? I think the current implementation keeps the paths in the order they are passed to the call to openApi(...)(endpoint1, endpoint2, ..., endpointN) (but we have no test for that, so I’m not sure).

[bmeesters]

As far as I can see the openApi(...)(endpoint1, endpoint2, ..., endpointN) will group the endpoints by tag using a simply groupBy. The result is then later processed sequentially by simply calling .iterator on the scala.Map and processed in that order. In any case the UI we use simply uses the order it is present in the JSON.

Would you be open for a PR? I can make something locally and confirm I can ensure an user defined order (defaulting to just a String Ord).

[bmeesters]

This is the piece of code (in endpoints4s.openapi.EndpointsWithCustomErrors#openApi) where the ordering changes:

endpoints
        .groupBy(_.path)
        .map { case (k, es) =>
        ...
        }

[julienrf]

Right, the groupBy breaks the ordering!

Do you think it would be enough to just keep the order in which the endpoints are passed to the openApi call? It would be simpler to implement it with scala/scala-library-next#51, but we can do it manually in the meantime.

[bmeesters]

The original order would be good enough for me (we just pass it alphabetically ourselves).

So what is your proposal? Use LinkedHashMap to keep the original insertion order or sort in another way?

[julienrf]

Yes, sorry if that was not clear, but if keeping the original insertion order works for you that would be a simple solution (we could make it more sophisticated in the future if needed). So yes, you will have to use a LinkedHashMap and to implement the groupBy operation by yourself (so that it returns a LinkedHashMap instead of a default Map).

[bmeesters]

NP :) I still think we might misunderstand each other. To be clear, we need a PR in endpoints4s to make this possible. The Map implementation in the openApi method has to change to use LinkedHashMap instead. I think everything else will work from there on out. Since the JSON creation (also in endpoints4s) will automatically use the original order since that map is used under the hood. We, as the users, never get to work with the map itself.

Shall I make a PR? I think it is just a one-liner

[julienrf]

I thought we could change the implementation of openApi without changing the signatures of other methods, but I might be wrong. In any case yes, a PR is welcome :)

[bmeesters]

Yes, I think so too, I will try 😄