@svengroup/openapi-to-pdf

Create PDF API reference documentation from OpenAPI 3.0.x specification files.

This tool works by first generating markdown content which is then converted into PDF.

Sample PDF Output

You may view the sample PDF output here: /samples/api-reference.pdf.

It shows a PDF version of /samples/openapi.yaml when the configuration at /samples/config.json is used.

Inclusions

This tool includes the following:

• Command line usage to generate PDF API reference documentation
• YAML and JSON OpenAPI 3.0.x support
• Fully configurable:
  • Header & footer
  • Cover page
  • Table of contents
  • Headings and texts
  • Custom Sections
  • PDF settings (thanks to md-to-pdf)
• Programmatic usage with markdown output
• TypeScript support

Installation

To install this tool run the one of the following commands:

npm i -g @svengroup/openapi-to-pdf # install globally
npm i -D @svengroup/openapi-to-pdf # install as a dev dependency
npm i @svengroup/openapi-to-pdf # install as a dependency

Usage

To convert an OpenAPI 3.0.x file to PDF simply run the following command:

openapi-to-pdf path/to/openapi.yaml

This will create an api-reference.pdf file in the same directory where the command was ran.

To view the different options for this tool, use the --help option:

openapi-to-pdf --help

Display Logic

To understand how this tool displays the OpenAPI specification in PDF format, see Display Logic.

Configuration

You can configure the PDF output by specifying a configuration file in the command:

openapi-to-pdf path/to/openapi.yaml --config path/to/config.json

To read more about how to configure your PDF output and the options available, see Configuration.

Programmatic Usage

You can also use this tool programmatically as a package in your Javascript and TypeScript projects:

import { generateMarkdown } from "@svengroup/openapi-to-pdf";

const md = generateMarkdown({/* OpenAPI V3 Schema Object */});

To read more about using this tool programmatically, see Programmatic Usage

To Do's

• Automated Tests
• Example Section in the PDF (JSON is a priority)
• Multi-file Support

Contribution

Read the Contribution Guide for details on how to contribute.

Acknowledgements

This tool was built upon the generous open source work of other developers, big thanks to:

• @simonhaenisch for md-to-pdf which powers markdown to PDF conversion for this tool.
• @seriousme for @seriousme/openapi-schema-validator which this tool uses to validate and parse OpenAPI files. The OpenAPIV3.Document interface is also directly from this package.
• TJ Holowaychuk for commander.js which made making the cli a lot easier.
• All the other developers who worked on the packages we use for this tool!