Automating the generation of API docs from schema (swagger / openapi) seems as important as any GitOps practice in 2022. At Aserto, we use the readme.com github actions to automatically update our API docs (aserto.readme.io) any time a new OpenAPI spec is committed.
I write the OpenAPI spec by hand as I haven’t found any tool to match my needs (nor is the API changing too often). And for the frontend to display the docs I couldn’t be any happier with <a href="https://stoplight.io/" rel="nofollow">https://stoplight.io/</a> (using their WebComponent for simplicity). I think I discovered this on the “APIs you won’t hate” podcast.
Shameless plug: here's my indie-project that converts an OpenAPI/Swagger spec into something that aims to look like Stripe's API Reference:
<a href="https://portal.dev" rel="nofollow">https://portal.dev</a><p>Here are a couple of example docs:
<a href="https://space-api.portaldocs.dev" rel="nofollow">https://space-api.portaldocs.dev</a> (and the OpenAPI behind it: <a href="https://github.com/portaldev/nasa-apod-api-docs/blob/main/openapi.yaml" rel="nofollow">https://github.com/portaldev/nasa-apod-api-docs/blob/main/op...</a>)<p><a href="https://recur-api-beta.portaldocs.dev" rel="nofollow">https://recur-api-beta.portaldocs.dev</a><p>At my previous workplace we've built the whole docs portal (including the API reference) as a custom static website with Contentful (a json CMS) underneath.
It was a real pain in the ass to edit and maintain, that's how I got the idea.
Our approach for generating API docs is generating a default UI including all the metadata that can be inferred from Typed DTOs and further enhanced with custom DTO attributes:<p><a href="https://docs.servicestack.net/api-explorer#api-customizations" rel="nofollow">https://docs.servicestack.net/api-explorer#api-customization...</a><p>But also allow users to define their own custom HTML Components for each API to provide full control to be able to include their own rich interactive content for any of their Types:<p><a href="https://docs.servicestack.net/api-explorer#api-docs" rel="nofollow">https://docs.servicestack.net/api-explorer#api-docs</a><p>That for optimal UX all gets bundled together with all the App's components into a single cached download.
I've never found anything better than Enunciate. Works very well and it's guaranteed always up to date because it's a compile time artifact. I really like that all the documentation and code are in one place, next to each other, and have a higher chance of being true and up to date than any other method