Generating HTML documentation with Swagger 2.x via Maven

Question

I am looking at generating some API documentation, hopefully using Swagger, in a few different projects of mine. Having never used Swagger, I am trying to find a very simple solution to generating HTML documents via Maven.

The underlying REST framework being used in these projects is Jersey. I found documentation from Swagger but it doesn't seem to have any examples of simply producing HTML files. Most of their examples seem to embed the API documentation into the actual service itself.

So my questions are:

• How can I generate HTML documentation with Swagger via Maven?
• Is attaching the documentation along with the service normal to do with REST applications?

Answer 1

You will need to use swagger-codegen to generate an HTML.

https://github.com/swagger-api/swagger-codegen#generating-static-html-api-documentation

To generate the HTML doc with swagger-codegen, you will first need to generate an OpenAPI documentation. Since you are already using Jersey as your REST framework, it is probably the easiest to pull in swagger as a dependency into your project and annotate all your API servlets. Doing so, will tell swagger to read all your code and generate an OpenAPI spec. You can follow the steps in https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration to get started.

Good luck!