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

Support for custom Swagger tags #41

Closed
ncreep opened this issue May 14, 2017 · 5 comments
Closed

Support for custom Swagger tags #41

ncreep opened this issue May 14, 2017 · 5 comments

Comments

@ncreep
Copy link
Contributor

ncreep commented May 14, 2017

Hi,

Currently, when rendering with the Swagger2dot0Json each path is tagged with the basePath of the module being rendered. As a result all routes in a given module have the same tag and are grouped in the UI accordingly.
Since I don't see how it would be possible to render a number of modules in the same Swagger file. Would it be possible to add support for adding custom tags to RouteSpec so that the Swagger renderer will be able to group by them?

Thanks

@daviddenton
Copy link
Owner

This one should be fairly simple to add - it should only touch the RouteSpec and the Swagger2dot0JsonRenderer. If you want to add it and submit a PR then that'd be great. Otherwise, let me know the relative urgency of the various issues and we'll look at them in order. :)

@ncreep
Copy link
Contributor Author

ncreep commented May 14, 2017

I'll look into submitting a PR on this issue, hopefully soon.
None of the issues are urgent, so feel free to address (or ignore) them in whatever order you see fit.

By the way, how complicated would it be to render a composite Swagger file from a number of modules at once (e.g., by using $ref)?

@daviddenton
Copy link
Owner

Assuming that you mean something along these lines http://azimi.me/2015/07/16/split-swagger-into-smaller-files.html it should be simple to add, since we just need to get the description base-paths from each of the other modules and use them to generate the composite JSON doc.

I'm envisaging that you've got a few modules sitting at various contexts, then a fallback root module with the composite renderer. Is that what you had in mind? So along the lines of:

/context1/swagger.json
/context2/swagger.json
/swagger.json <-- composite with $refs

The trickiest part is getting the API to look nice. Easiest option would probably be to have a CompositeModule function which takes a bunch of other modules or creates them in a builder like way (see below):

CompositeModule(Root, CompositeRenderer)
.withModules(m1, m2, m3)

However, since the Module is not typed by the Renderer implementation, it would currently not be possible to have the compiler guarantee that all of the submodules were in fact Swagger modules, so an alternative is to have the "super" module create the submodules and pass them to a function for configuration:

val m: Module = SwaggerCompositeModule(Root)
.withModule(_ / "context", {
    module => 
        module.withRoute(r1).withRoute(r2)
})

Do either of those 2 seem reasonable?

@ncreep
Copy link
Contributor Author

ncreep commented May 14, 2017

Since I like compile-time guarantees, I would lean towards the second approach. Though my perspective is still limited by lack of familiarity with the innards of Fintrospect.

What I can say from the bit of experience that I already have, and the second solution seems to hint at it, is that I'm missing the ability to aggregate and process routes without committing them to a specific renderer. And maybe I'm reinventing the wheel or something, but at the moment I use simple wrappers around groups of RouteSpecs with a toModule method that converts all of them at once to a Module once I'm ready for it. I also use wrappers to aggregate a bunch of routes but with the ability to add a common path-prefix to all of them at some later point.

@daviddenton
Copy link
Owner

Custom tags is in 14.17.0. I'm opening another issue for the composite Swagger renderer.

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

2 participants