Generating API documentation
There are many different tools and services that allow you to display live API documentation from the OpenAPI specification. You can either self-host the API documentation using tools like ReDoc or Swagger UI or go with a SaaS which provides hosted documentation. Usually, these services offer not only API documentation capabilities but cover the entire API lifecycle. In that category, we have Postman, Stoplight, Swagger Hub, ApiMatic, and a few.
After trying out different services, we finally chose to self-host the ReDoc. We liked their three-column design and presenting the endpoint parameters, for example, payloads and responses.
We also loved how easy it was to deploy the documentation with ReDoc. You can use their bundled JavaScript and specify URL to your Open API specifications. The code snippet below is everything you need.
<!DOCTYPE html
<html>
<head>
<title>PDF Generator API Documentation</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='https://pdfgeneratorapi.com/api/v3'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>>Generating code-snippets
For us, it was important that developers can try out our API as easy as possible. Therefore we wanted to provide code samples in different programming languages. Creating and maintaining code samples in other languages can be complicated if you don’t have the know-how in the team.
After researching the Internet, we found this small node module that uses the openapi-snippet generator to create code samples and enrich your Open API specification. You can just run the following command, and you will have code samples for each of your API endpoints.
./node_modules/.bin/snippet-enricher-cli --input=openapi.yaml > openapi-with-examples.jsonAnd the result is nice looking code samples in your documentation.
Generating HTTP API clients
If managing code-snippets is time-consuming, keeping your API clients up to date is a nightmare, especially if you have a small team. So, besides generating code-snippets for each API endpoint, we also wanted to auto-generate HTTP clients for our API.
This task turned out to be more complicated than we initially thought, but we ended up with the OpenAPI Generator, a fork from Swagger Code Generator. The main advantages of the OpenAPI Generator were better documentation and the easy to use node module. What we found important was specifying a configuration file for each programming language. You can find a set of available configuration options for each language here.
We also created a small bash script to help us automate the code generation and fix some issues in the generated README file. We have another script that automatically pushes client updates to GitHub. This means that by running a single bash script, we create HTTP clients for five target languages (Python, Java, JavaScript, PHP and Ruby) and publish updates to GitHub.
#!/bin/bas
cd $(dirname $0)
OPEN_API_DOC=/path-to-procject/api-docs.yaml
LANG=$1
OUTPUT_DIR=./$LANG
GIT_REPO="$LANG-client"
CONFIG=./config/$LANG.yaml
rm -rf OUTPUT_DIR
npx openapi-generator generate -g $LANG -i $OPEN_API_DOC -o $OUTPUT_DIR -c $CONFIG --git-user-id=$GIT_USER --git-repo-id=$GIT_REPO --git-host=github.com
sed -i 's|\\"|"|g' $OUTPUT_DIR/README.md
sed -i 's|*@dev|master|g' $OUTPUT_DIR/README.mdhIf you wish to know more about Open API Generator, I suggest reading the Introduction to OpenAPI Generator by Kristopher Sandoval on Nordic APIs.
Summary
The chosen tools were only the best for us, and I suggest that before you start documenting your APIs, you would also do your research with some trials on different tools. You might find some other combination that suits you much better. Selecting the proper tooling will save you much time. The good part is that once you have the specification done, it’s easy to try out different tools and hosting options.
Also, you can check out our API documentation here.
And finally, feel free to contact us as we are always open to share our experience and help fellow developers to succeed! — Tanel Tähepõld, Founder of PDF Generator API