Automatically generate RESTful API documentation with Swagger

[ndbroadbent]

One thing I really like about go-restful is their built-in Swagger integration. Check out the example project: https://github.com/emicklei/mora#swagger

Some things I really love about Gin is the focus on performance, and overall, it just seems like a much better designed framework. However, I think that auto-generated documentation with Swagger is pretty awesome. It makes it easy for new engineers to get up-to-speed quickly by reading through the docs, and I especially love the way you can auto-generate API clients for lots of different languages.

I'm not sure how involved this change would be, I'm not sure if this could be done as an extension. But we could probably take lots of inspiration from (or just copy) the swagger code from go-restful (MIT licensed).

Anyway, this is not a huge priority for me, just a nice to have.

[rogeriomarques]

+1

[phalt]

+1

[redstrike]

+1, swagger is very useful for API development

[matejkramny]

👍

[javierprovecho]

@phalt @redstrike @matejkramny @rogeriomarques @ndbroadbent I'll add support for it with v0.6 in mind. Thank you for submitting this request.

[salimane]

+1

[colthreepv]

I'm gonna raise the biddings on this issue, Ok for Swagger, but why not RAML?
In my personal experience using both swagger and raml barebone, the latter has a better explained specification and has a more pragmatic approach.

I'll explore what can be done with my limited golang skills, and keep you posted

[colthreepv]

One of the main concerns in thinking this feature out, is design this swagger/raml feature producing a base json/raml document that can be extended to let the user exploit the full-feature set of their API specifications.

I hardly seen that in other frameworks, but I'm hoping someone could propose some input regarding this

[njuettner]

+1 for swagger support

[itsjamie]

I'm surprised there isn't someone who has created a parser that looks at an AST + attached routes for net/http to generate Swagger/RAML style documentation.

If it isn't a project, perhaps that would be the better method of implementation for this? Rather than having it part of Gin core, if it was a separate binary that scanned a package?

[colthreepv]

I think to externalize API documentation, gin.router should be exported (so Router).
Moreso, I think model validation should be expanded before implementing API documentation, since there is a big difference between the vastity of API validation options and gin ones.