Benefits of Open API — How we generate documentation, code-snippets and clients (Part 2 of 2)
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.
<title>PDF Generator API Documentation</title>
<!-- needed for adaptive design -->
<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">
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
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.json
And 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.
cd $(dirname $0)
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.mdh
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