We had some problems with adding the v3 spec: All of the route names in Mojolicious are generated from the operationId of the route in the spec. So if two routes had the same operationId, even if they were in different files, the later one would overwrite the former one, and things would go wrong.
We fixed this by ensuring all the operationIds were unique across the two files, but this is a cumbersome approach and prone to forgetting.
Instead, we should use spec_route_name in the top-level of the spec to set the prefix for all the operations in the file. This way we can easily copy the file, change a few top-level things, and then move on. This also means that we can share routes between specs more easily, since not all routes will change between versions, and pointing back to a previous spec's version of a route will explicitly declare that it hasn't changed.
Each spec file should have a spec_route_name, which should be the version of the file (v1 and v3). The v3 spec file should have all of the v3_ prefixes removed from its operationId properties.
Finally, the documentation website will need to have its URLs updated. You will need to check to see how the internal fragment IDs are rendered by Swagger, and then update the links on the index page (/share/templates/index.html.ep).
We had some problems with adding the v3 spec: All of the route names in Mojolicious are generated from the
operationIdof the route in the spec. So if two routes had the sameoperationId, even if they were in different files, the later one would overwrite the former one, and things would go wrong.We fixed this by ensuring all the
operationIds were unique across the two files, but this is a cumbersome approach and prone to forgetting.Instead, we should use
spec_route_namein the top-level of the spec to set the prefix for all the operations in the file. This way we can easily copy the file, change a few top-level things, and then move on. This also means that we can share routes between specs more easily, since not all routes will change between versions, and pointing back to a previous spec's version of a route will explicitly declare that it hasn't changed.Each spec file should have a
spec_route_name, which should be the version of the file (v1andv3). Thev3spec file should have all of thev3_prefixes removed from itsoperationIdproperties.Finally, the documentation website will need to have its URLs updated. You will need to check to see how the internal fragment IDs are rendered by Swagger, and then update the links on the index page (
/share/templates/index.html.ep).