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?

DocBaker for OpenAPI does exactly that: https://apidoc.curvednebula.com/ — Illya S, Apr 04 '22 at 07:59

Helen · Answer 1 · 2019-06-11T20:08:27.983

29

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:

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

edited Jun 11 '19 at 20:08

answered Feb 04 '19 at 22:25

Helen

87,344
17
243
314

1

Fyi, there's the 'openapi-generator-gradle-plugin' which makes steps 1 to 4 incl redundant. – Alex Sep 24 '20 at 14:53
There's a lot of generators in openapitools/openapi-generator-cli (docker image), but none of them are PDF. – Aaron Wright May 24 '22 at 20:16

score 10 · Answer 2 · answered Aug 12 '19 at 10:00

10

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

answered Aug 12 '19 at 10:00

aleung

9,848
3
55
69

It also doesn't support many of the features of OpenAPI 3. It seems to fall flat on OneOf or AnyOf. – Aaron Wright May 24 '22 at 19:33

score 4 · Answer 3 · answered Nov 27 '20 at 17:01

4

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.

answered Nov 27 '20 at 17:01

Boommeister

1,591
2
15
54

2

Didn't do it well at all using an OpenAPI "3.0.1" spec with 3 definitions – user1323562 Oct 28 '21 at 14:20
That didn't render any operation at all – zed Jun 16 '22 at 12:03

Illya S · Answer 4 · 2023-09-02T14:52:39.573

3

ApiBake - OpenAPI to PDF: https://www.npmjs.com/package/apibake I'm the developer of the tool.

2023 UPDATE: The tool has been converted from Dart to Node.js, added yaml support and fixed a few issues.

The focus of the project is to generate visually simple, yet useful document, with bookmarks and type links for easy navigation. I.e. object definitions in the PDF are easy to copy and use in TypeScript/JavaScript code. Now working on custom styling of the output document. Feedback is welcome.

edited Sep 02 '23 at 14:52

answered Apr 04 '22 at 07:30

Illya S

161
1
12

1

This looked useful for my usecase, but only supports JSON. Any plans to add YAML support? – tddmonkey May 17 '22 at 07:23
I converted an openapi yaml spec to json from swagger editor to try this tool but getting the error "invalid openapi json file". It'll be good to add an example on the homepage itself for more clarity on expected input. – Akshay May 18 '22 at 06:08
1

No source, just an executable download? No good. – Aaron Wright May 24 '22 at 19:46
Is it 3.x.x openapi json? The tool only supports 3.x.x version. Actually, you are right. Will open the sources. – Illya S May 25 '22 at 20:11
Source Code is available: https://github.com/curvednebula/docbaker-cli – Illya S May 28 '22 at 16:10
Showed "invalid openapi json file" for valid files and the output is visually quite poor unfortunately – zed Jun 16 '22 at 12:03
@zed this issue should be fixed in the latest update – Illya S Sep 02 '23 at 14:57

score 2 · Answer 5 · answered Sep 25 '20 at 15:59

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': 'inbox@example.com',
    ])
}

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.

score 1 · Answer 6 · answered Apr 29 '22 at 09:27

1

The easiest and nicest solution I found it is just using the usual https://editor.swagger.io/. Once you are happy with the generated outcome (on the right), just drag the central cursor on the left (to cover your source code) in order to visualise only the final documentation. Then if you use Chrome (similarly for Firefox), just (right button in the screen or from menu) choose "Print" and for "Destination" select "Save As PDF".

answered Apr 29 '22 at 09:27

Randomize

8,651
18
78
133

That requires lots of clicking and expanding schemas, and so it is not very reproducible. – Aaron Wright May 24 '22 at 19:47
lots of clicks? eventually the opposite. Not reproducible? what you mean? it is not meant to be a "programmatic" method of course – Randomize May 25 '22 at 08:56

How to generate a PDF or markup from OpenAPI 3.0?

6 Answers6