Support for custom Swagger tags

[ncreep]

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]

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]

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]

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]

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]

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