Generate swagger-api with existing vert.x project

Question

I have an existing vert.x project which became too heavyweight and intransparent.*

To replace it I am checking for several options, one of those being swagger.

Does anyone know an opensource lib which can create a swagger-api from vert.x?

Swagger generates APIs and documents them in a friendly manner. Now, I understand that you have APIs already. Are you looking to document them, in hope that it will improve transparency? — Alexey Soshin, Jun 21 '17 at 15:36
Hello @Alexey Soshin, I thought about following this plan: 1. Generate swagger-api documentation with existing vert.x code. 2. Generate nodejs or spring boot server stubs using the newly created swagger-api 3. enjoy new vert.x-free life. — She-Ra, Jun 23 '17 at 07:36

score 2 · Accepted Answer · answered Jun 23 '17 at 08:18

I'm not aware of something like that. The only vertx-swagger integration does exactly the opposite: generates Vertx router based on Swagger configuration: https://github.com/phiz71/vertx-swagger

What you can do is generate all routes using this solution: List all registered routes in Vertx

Then add them manually to Swagger Editor, and finally generate your new APIs with Swagger Codegen

Do mind that rewriting you application into another language or framework probably won't solve your problems. NodeJS is not as typesafe as Vertx, and SpringBoot is not as concurrent as Vertx. But if you don't need typesafety or concurrency, both are viable options, of course.

Thank you Alexey, there seems to be no other way but add the endpoints manually — She-Ra, Jun 26 '17 at 14:46

outofcoffee · Answer 2 · 2018-01-21T11:16:43.943

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

(Disclosure: It's my open source project)

Example usage:

// your normal Vert.x Web Router with paths etc.
Router router = Router.router(vertx);
router.post("/users").handler( routingContext -> { /* etc... */ });
router.get("/users/:userId").handler( routingContext -> { /* etc... */ });

// publish the Swagger/OpenAPI specification to a URL
RouterSpecGenerator.publishApiDocs(router, "/api/spec");

You can obtain YAML or JSON versions of the specification by adding the appropriate file extension.

For example, fetching /api/spec.yaml would produce:

openapi: "3.0.1"
info:
  title: "Vert.x APIs"
  description: "This specification was generated from a Vert.x Web Router."
paths:
  /users:
    post:
      parameters: []
  /users/{userId}:
    get:
      parameters:
      - name: "userId"
        required: true
        allowEmptyValue: false

Generate swagger-api with existing vert.x project

2 Answers2