Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add spec_route_name to all API specs #12

Open
preaction opened this issue Jun 8, 2017 · 0 comments
Open

Add spec_route_name to all API specs #12

preaction opened this issue Jun 8, 2017 · 0 comments

Comments

@preaction
Copy link
Member

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant