You’ve built a brilliant API, well done! But hold up, people are trying to use it, and there’s no public-facing documentation. Your API and the docs are private, and require a special VPN, SAML, and/or some sort of OAuth proxy that requires not just a GitHub account, but that GitHub user needs to be part of your organization.
Whatever the approach, there are often users outside of this super-secure realm that needs access to the documentation. Maybe it’s a customer who is paying a bunch to get access to some of your data. Maybe it’s a contractor who is going to be doing some work on the API and doesn’t want to guess the contract. Maybe it’s a different department that is in a different GitHub organization, e.g.: an acquired company wants to integrate.
So what do you do? A common approach is to export the API docs as a PDF, then email it over. Sure. That’ll work, but how?!
Step 1: Create an OpenAPI Description
For a lot of you reading this, you’ll already have an OpenAPI description. Someone on your team probably created it before anyone started programming the API so that everyone could be sure the right thing was being built in the first place. Other teams might have generated OpenAPI using annotations added to the code.
If you’ve not got any OpenAPI yet head over to Stoplight Studio or look for another Visual OpenAPI Editor to put together some OpenAPI for your API. Each PDF conversion approach will have an example you can try.
Step 2: Convert to PDF
Print from Browser
Just to get this one out of the way, some folks recommend printing their existing API documentation. They load it up in their browser, and hit “Print > Save as PDF”. This is not likely to give great results.
The popular API documentation tools use the “three-column” layout, popularized by Stripe API Reference with a navigation bar on the left and other stuff on the right, which looks daft squashed onto an A4 page.
Then there’s the interactive elements in most good API documentation, like interactive HTTP consoles, parameter lists with expandable nested content, and generally a bunch of hyperlinks that don’t work when you print them.
It’s hard to see in a small screenshot, but the printed version of these excellent docs shows expandable links that cannot be clicked, meaning whoever looks at this PDF cannot see any of the child properties of objects. There was also a GDPR warning floating halfway down the first page.
If your API docs are using a really clever print.css that hides everything not useful in a print context and expanded everything that should be expanded, it might just work out fine. This is rare, but worth trying. If it doesn’t work, try another one of these approaches.
Swagger2pdf
A popular CLI/NodeJS tool exists called swagger2pdf, which like most of the older third-party “Swagger” tools only supports OpenAPI v2.0. It does at least support both JSON and YAML, unlike a lot of those older tools.
npm install -g swagger-spec-to-pdf
wget https://stoplightio.github.io/sample-specs/reference/instagram/instagram.yaml
swagger2pdf -y -s instagram.yamlThis tool works by spinning up a browser instance, which then shoves the OpenAPI into Swagger UI, and automatically prints the output. Once that process has finished you should see a file in the current directory called api.pdf.
Again there are plenty of links cluttering the PDF up which will not work, and only the first level of nesting is displayed in the schema, but it’s something.
RapiPDF
Another tool that works with OpenAPI v3.0 & v2.0 is RapiPDF. This is also an NPM module, but it works a little differently than you might expect. Instead of working as a CLI tool that creates a PDF in some sort of build process, this is a Web Component that produces a Generate button.
This could be added to your API Reference Documentation, so that people can download the PDF when needed, so that it can be sent off by email, shoved into Dropbox, etc.
To try it out, make a generate.html and give it the following content:
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/rapipdf/dist/rapipdf-min.js"></script>
</head>
<body>
<rapi-pdf style="width:700px; height:40px; font-size:18px;" spec-url="https://stoplightio.github.io/sample-specs/reference/instagram/instagram.yaml" >
</rapi-pdf>
</body>
</html>Then open that file in the browser (e.g.: $ open generate.html) and click the Generate button to trigger a download of the PDF.
RapiPDF creates a more useful output, especially for schemas with a lot of nesting (objects inside objects), and doesn’t contain any links or elements that shouldn’t be in a PDF.
As this one is a bit tricky to show off in a single screenshot, take a look at the resulting PDF here.
Alternative Workflows
Instead of doing any of this, it might be worth taking a step back, and thinking “Why do I need to make a PDF?” Somebody may have asked you to do it, or you’ve decided to do it because it’s something you’ve always done, but… do you need to?
The base use-case here is often an API that may or may not be private but definitely has private or “internal” documentation, and somebody who is not in that “in the group” needs access to it. There are a lot of other ways to do this.
For starters, you could generate HTML with any of the many free and open-source tools that create Beautiful API Reference Documentation, and host that on a password-protected Amazon S3 bucket then email the password and URL instead of emailing a PDF. If the S3 bucket is updated with new HTML by your continuous integration server then you don’t have to worry about emailing over updated PDFs.
If you don’t want to set up any of this, Stoplight handles the workflow for you out of the box. There’s no need to email PDFs around or roll your own password-protected hosted documentation. We already have privately hosted documentation based on SAML and version-control-based SSO from GitHub, BitBucket, etc., then you can whitelist email address domains too.
Maybe you work at protectedcompany.com and you want anyone at somecustomer.com to get access to certain projects? Whitelist somecustomer.com with Guest privileges, get them to sign-up, and add them to the specific projects they should be allowed to see. Maybe you have a contractor who should be treated like an employee and have access to seeing most APIs? Make them a Viewer and now they can see any internal projects.
There’s more granular functionality on its way, with Workspace Groups helping split Workspaces into smaller more flexible permissions groups, and Share Documentation which will let API designers share any projects with anyone without having to mess with permissions. All this will get easier as these new bits of functionality roll out, but it’s already a whole lot easier than repeatedly emailing PDFs around, and already a whole lot more useful.
