How to generate a PDF or markup from OpenAPI 3.0?

Question

I have an OpenAPI 3.0 spec and I want to generate a PDF out of it so that it can be given to the end users.

Currently, tools like swagger-spec-to-pdf or swagger2markup only support Swagger 2.0 but not OpenAPI 3.0. Is it possible to generate a PDF from an OpenAPI 3.0 spec without converting it to Swagger 2.0?

Answer 1

A possible solution is to convert your OpenAPI 3.0 definition to an HTML doc, then use a browser's "Save to PDF" feature to convert HTML to PDF.

Follow these steps:

1. Go to https://editor.swagger.io.
2. Paste your OpenAPI 3.0 YAML/JSON definition.
3. Select Generate Client > html.
4. Download & unzip the file.
5. Open the index.html page in a browser, e.g. Chrome.
6. Select File > Print, change the Destination to Save as PDF, and save the page.

Answer 2

I just found RapiPDF which is able to generate PDF from OpenAPI 3.0 definition.

But it still isn't an ideal tool I'm looking for. I found these limitations so far:

• No CLI, runs only in browser. So I can't use it in an automate pipeline.
• Callback is not supported
• No example in generated document

Answer 3

You can use this site and post your OpenAPI 3.0 spec (in json) directly into it. It's the easiest way, I think and the generated PDF looks pretty.

Answer 4

The following 2 packages helped me generate a PDF from OpenAPI json file:

• org.openapitools:openapi-generator-gradle-plugin:5.0.0-beta2
• org.asciidoctor:asciidoctor-gradle-jvm-pdf:3.2.0

Apply the relevant Plugin classes and the rest is pretty straight-forward task configuration. This is my groovy plugin but it shouldn't be difficult to find the corresponding gradle DSL extensions should you need to.

project.plugins.apply OpenApiGeneratorPlugin
GenerateTask adoc = project.tasks.withType(GenerateTask).iterator().next()
adoc.with {
    it.input = swagger.outputDir.path + '/' + swagger.outputFileName + '.json'
    it.generatorName.set 'asciidoc'
    it.outputDir.set swagger.outputDir.path

    // Leaving the below option empty can cause rendering issues
    it.configOptions.putAll([
        'infoUrl'  : 'https://example.com',
        'infoEmail': '[email protected]',
    ])
}

project.plugins.apply AsciidoctorJPdfPlugin
project.tasks.withType(AsciidoctorPdfTask).iterator().next().with {
    it.sourceDir = adoc.outputDir
    it.outputDir = it.sourceDir
}

Let me know if there are questions about (or syntax errors in) this snippet.