Vertx-web: Swagger Support

[sathishk]

How to integrate Swagger into Vertx based REST API ?

[aesteve]

I guess someone should write this kind of adapter for the vertx-web Router.

Not sure how it would detect lambdas, and not sure how one would declare query parameters.

But for sure it would be an interesting implementation.

[pmlopes]

Hi,

I'd suggest you to use: http://editor.swagger.io as a base editor, and then export the yaml file as json and serve it from your app using the static resource handler and the swagger-ui app to render the documentation.

The idea of using an external file has the most flexibility in terms of documentation however you need to be careful and keep the code in sync with the yaml.

[pmlopes]

See: http://vertx.io/blog/contract-driven-rest-services-with-vert-x3/index.html it is not specific to swagger but RAML but shows the basic concepts that could also be achieved with Swagger.

• swagger json: http://swagger.io/swagger-editor/
• swagger api console: http://swagger.io/swagger-ui/
• validate contract: https://github.com/RobWin/assertj-swagger

[futurechan]

Is there no way to have the swagger docs generated automatically based on the vertx configuration?

[pmlopes]

No, we have no code for that.

[futurechan]

@pmlopes is it possible to get the list of routes from vertx and use reflection to generate the swagger documentation?

[gdrte]

Jooby framework(Jooby.org) have this kind of support. It parses javadoc and generates a routespec file during compile time. It supports RAML and Swagger. So I think it is possible.

[vietj]

do you mean that @gdrte http://jooby.org/doc/spec/#definition-writing-doc ?

[gdrte]

Yes, I am referring exactly that.

[rdruss]

Ok, I know this issue is closed as won't fix, but does this address the original issue: https://github.com/zalando-incubator/axiom-web/tree/master/vertx-swagger

Looking at the dependencies, it's currently based on vertx-web and vertx-dropwizard-metrics v3.1.0

[Swasthikashree]

@gdrte - If the services are defined in the way Jooby asks for, vertx wont be able to recognize it. Has anyone tried it?

[aesteve]

Hi,

I'll give my 2 cents on Swagger documentation auto-generate.

I think for now, it'd be really hard to generate a full Swagger doc with vertx-web as is. A lot of the "doc" is borrowed within the implementation (expected parameter types, etc.).

So the only solution would be to "annotate" the routes to generate the Swagger documentation. But this is not polyglot-friendly, and I agree with that.

I exposed the best solution I have in mind (hoping there's a better one, though) here : https://groups.google.com/forum/#!msg/vertx/01tCUjTm01s/cLBrUMqdCAAJ;context-place=forum/vertx

With such a functional API you could pretty much generate everything.

router.route("/api/1/test")
  .ifAccepts(APPLICATION_JSON)
  .authenticated()
  .withIntParam("a")
  .withDateParam("date")
  .ensure(RateLimitChecker::notThrottled).orFail(ServerResponse::tooManyRequests)
  .handler(/* */)
  .future(ServerResponse::Ok)
  .onFailure(ServerResponse::InternalServerError)

[pmlopes]

There was a google summer of code project on this front, Google will announce the selected students on May 4th 16:00CET, lets continue the discussion then.

If we have a selected student for this this thread will be of great value.

[slinkydeveloper]

Hi to everybody! I've been selected to work on it during GSOC 2017. Check it out: https://groups.google.com/forum/?fromgroups#!topic/vertx-dev/rU4FOhMBkFU

[debashisdeb]

@slinkydeveloper is there any progress made on this yet ? Is the annotations support to generate dynamic api docs coming up for Vert.x any soon ?

[slinkydeveloper]

If you want to give a look at my progress: https://github.com/vert-x3/vertx-web/pull/666

[outofcoffee]

@futurechan @pmlopes Here's an open source project (for the JVM) that generates a Swagger/OpenAPI specification from your existing Vert.x router:

https://github.com/outofcoffee/vertx-oas

[vlatk0o]

@outofcoffee Can you make some tutorial how to import your project? I have tried to import it but it can not be imported as project... And can you give me a contact email?

[ckaratzas]

Check this also:
https://github.com/ckaratzas/vertx-openapi-spec-generator
It doesn't cover all openapi 3 spec mappings but contains the blueprint on how to auto generate spec from code. With few changes it can support more features.