sendle / print-openapi

Generate a printable HTML file from your OpenAPI spec

Print OpenAPI

This tool takes an OpenAPI file and spits out a printable, static HTML file. Since most browsers have a 'Print to PDF' function, you can use this to generate nice PDFs of your OpenAPI specs.

Why?

Most OpenAPI tooling focuses on creating fancy displays that you can click on, send API requests with, etc. But sometimes you just need a plain, easily-readable, and static copy of your API docs. We needed that here at Sendle for our internal documentation, so we built this tool!

How?

The tool uses the OpenAPI tooling released by ReadMe. Go check them out if you're after a nice developer hub – their offering is pretty cool!

Installation

$ npm install -g print-openapi

Usage

$ print-openapi export-html bbs-openapi.yaml bbs-openapi.html

Generate a printable HTML file from the bbs-openapi.yaml OpenAPI file, including all paths and pages.

---

$ print-openapi export-html --tag moderation bbs-openapi.yaml bbs-moderation-openapi.html

Generate a printable HTML file from the bbs-openapi.yaml OpenAPI file, only including paths and pages that have the moderation tag.

---

$ print-openapi deref --tag system-messages --tag sysmsgv2 bbs-openapi.yaml ../sysmsg.openapi.json

Create a new OpenAPI file called sysmsg.openapi.json. This file only contains the paths and pages from bbs-openapi.yaml with either the system-messages or sysmsgv2 tags.

Markdown pages

We've defined the x-pages extension, which lets you define arbitrary markdown pages to be displayed on the exported HTML files. See the bottom of that extension page for our future plans with it!

We support ReadMe-Flavoured Markdown, including their syntax for Callouts.

Tags

--tag and -t refer to the tags that can be assigned to OpenAPI operations, and to our custom markdown pages as defined our x-pages extension.

When using print-openapi, by default all pages and operations are exported. However, when tags are specified the tool will only include pages and operations with those tags. See the example specs in /examples/.

License

Released under the MIT license. See LICENSE for details.

print-openapi's Issues

Allow commands to be run per tag

For example, export-html-per-tag and deref-openapi-per-tag, which will create a single output file for each tag in the input.

Display version

Version number is useful, show it.

Support for documenting webhooks

OpenAPI 3.1 allows documenting webhooks – we should look at documenting those.

Display date in exports

Probably a flag to include the current date in exported HTML files.

Add contributor guidelines

Define whether we allow external contributions/PRs/issues and all. Reference contributor files from other projects for inspiration!

Interesting OpenAPI extensions

Here are some extensions which are interesting:

• x-visibility and x-status
• x-unofficialSpec
• x-logo and another x-logo
• x-summary and x-description for Path Item objects
• x-codeSamples and Readme's version
• x-contracts

Speed up

Figure out why this takes so long to run

Theming

Include some examples

Sean mentioned that we should show off the exported html and pdfs and all. Once we review the formatting next week, I'll export some example files to live in the examples folder.

Github Action support