Skip to main content

Comparing OpenAPI Generator Documentation Templates

In addition to API reference docs, developers expect documentation specific to your SDK.

Let’s compare different templates for generating documentation with OpenAPI generator.

dynamic htmlhtmlhtml2markdown
Explain methods and params🟒🟒🟒🟒
Models and properties🟒🟒🟒🟒
Enums allowed valuesπŸŸ’πŸŸ’πŸŸ’πŸ”΄
Display base urlπŸŸ’πŸ”΄πŸ”΄πŸŸ’
Response headersπŸ”΄πŸ”΄πŸŸ‘πŸ”΄
Example JSON responseπŸ”΄πŸŸ‘πŸ”΄πŸ”΄
Runnable code sampleπŸ”΄πŸ”΄πŸŸ‘πŸ”΄
How authentication worksπŸ”΄πŸ”΄πŸ”΄πŸ”΄
Legend
🟒Good
🟑Incomplete
πŸ”΄Missing

Try it yourself, by running this command in your terminal

docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli:v6.2.1 generate \
-i https://raw.githubusercontent.com/apimatic/petstore/main/oas/petstore.yaml \
-g html2 \
-o /local/html2

HTML2 is the most visually appealing template and attempts to generate runnable code, but sadly misses the mark. For example, the create pets method expects a native Pet object, but instead a JSON string is provided. For strongly typed languages, the syntax is invalid. This pattern is repeated across all languages.

OpenAPI Generator documentation screenshot

Don’t despair, you can clone the OpenAPI generator repository and modify the mustache templates to address many of these shortcomings. I will say that generating runnable code snippets in multiple languages was a sizable challenging and at Xero we ended up adding complex vendor extensions to achieve it. Check out Xero’s SDK documentation.

Next, let's look APIMatic a service to generate your SDKs and developer docs.

Share this page: