Generate PDF from Swagger API documentation for grails app

with 1 Comment

There are three steps to generate PDF from swagger documentation:

1. Rest-api -> swagger.json
2. Swagger.json -> Asciidoc: swagger2markup plugin
3. Asciidoc -> PDF: asciidoctor plugin

File swagger.json was generated using swagger-core library and its modules (swagger-models and swagger-annotations).

After swagger.json is generated then Swagger2Markup comes into operation. Swagger2Markup converts a Swagger JSON file into several AsciiDoc Markdown documents. It needs to add the library to the project’s classpath to start using it.

Conversion of a Swagger file

  1. Create a Swagger2MarkupConverter.Builder by specifying the Path/URL to the file
  2.  Define config of the Swagger2MarkupConverter
  3.  Build an instance of the Swagger2MarkupConverter
  4.  Invoke toFolder by specifying the output directory

In the output directory is generated files: overview.adoc, paths.adoc, security.adoc, definitions.adoc.

The library to convert the files to pdf is :

Conversion of the .adoc files to PDF

  1. Create a new instance of Asciidoctor
  2. Add all file in one
  3. Create attributes builder. Here we can set if table of contents should be rendered or not, define doc type attribute and etc.
  4. Creates options builder instance and defines backend option
  5. Parse the AsciiDoc source input into an Document and render it to the specified backend format. In our case it will be PDF document

One Response

  1. Saqib Ahmed
    | Reply

    It would have been better if this guide is a bit more elaborate. Like I’d really want to see the names of the files in which swagger2markup API is called and so on. Nice article by the way. :)

Leave a Reply