discussion: swagger support

[laher]

Hi Julien,

I just set up a project called Swugger to show how swagger support might be acheived for httprouter. It's working, and it uses go-restful's swagger support to document some 'dummy' go-restful routes while setting up real routes in httprouter. I'd like to actually just fork go-restful and strip it back into a swagger provider for httprouter (and others), but before I do that I'd like to check in with you first.

So, I have 2 questions:

Firstly, have you considered Swagger support already? Or any other form of service description feature? Are you already working on something like this for httprouter? For example, it might be nice to optionally represent routing documentation inside httprouter's node, but then on the other hand, it would add baggage to a small and tidy framework.

Secondly, if you're interested at all, could you take a look at swugger (see the readme), and see if it's an interesting idea to you. If you have any feelings about how you might do things differently, I'd love to know.

Feedback aside I'll just go ahead and make a less 'ugger' version of swugger (forking and stripping back go-restful back towards swagger support only. I may also change it to use a less fluent-interface style of library - just adding a RouteDoc{} struct to each route definition might feel more Go-ish to me).

Anyway, there it is, thanks for the awesome work on making a fast router.

[julienschmidt]

Hi Am,
sorry for my late reply.

I just set up a project called Swugger to show how swagger support might be acheived for httprouter. It's working, and it uses go-restful's swagger support to document some 'dummy' go-restful routes while setting up real routes in httprouter.

It looks nice!

Firstly, have you considered Swagger support already?

No

Or any other form of service description feature?

No

Are you already working on something like this for httprouter?

Concluding from the previous answers: No

For example, it might be nice to optionally represent routing documentation inside httprouter's node, but then on the other hand, it would add baggage to a small and tidy framework.

Indeed. I'd prefer to keep the nodes lightweight.

Secondly, if you're interested at all, could you take a look at swugger (see the readme), and see if it's an interesting idea to you.

It is! I think it would be a very nice add-on. Not only to HttpRouter, it would be useful with (almost) any router. On the other side, I want to keep this router as simple as possible. Therefore including native support is not really an option. The best solution to me would be 3rd-party package like your current swugger project.
To make this work seamless, you need access to the routing info. Using a proxy handler is not really a nice solution, since there is no guarantee that every route is called. Moreover it affects the performance. A nicer solution would probably to allow to register handlers, which are called when a new route is added. What do you think? Do you need any other data from the router?

[laher]

Hey there, sorry for the extremely delayed response, and thanks for responding & offering a solution.

Yes I like the idea of registering a 'handler' which receives routing information, but, I think the routing information would be missing docs & input/output parameters - an important part of Swagger. I guess this could be passed in as a 'metadata' parameter (containing the method docs plus parameter specs).

At a guess I'd say that this metadata object would only be interesting to Swagger users (i.e. just a fraction of httprouter's audience), so it might not make sense to add the metadata to your API. So, I think a Swugger-like wrapper would still be needed in combination with this handler concept.

The information I'd hope for a route handler to receive would be:

• HTTP Method
• Path
• Supported content types (request & response), if possible.
• Metadata (if possible):
  • Method doc
  • Parameter specs (post-data/headers/response, including types)
  • Parameter docs

It might be worth checking out the Swagger docs for further details. Otherwise, just ask
Cheers

[buddhamagnet]

@laher not sure if this is useful, but I maintain a package that plugs RAML into your router of choice with examples for httprouter: https://github.com/EconomistDigitalSolutions/ramlapi

[avonar]

there are still no changes here?
any standart way to use swagger?...

[riley-ashton]

I commented a basic solution here using swag annotations (dev dependency, not runtime) and just static serving a folder containing swagger.yaml and a static html file:

#362 (comment)

No runtime dependencies or changes needed to httprouter