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.
Totally agree! Our mindset at ReadMe is that docs should be split into two parts... there's things automation can do better (reference guides, code samples, interactivity, etc) and things people can do better (marketing pages, tactical guides, etc).
(Feel free to shoot me an email if you have any product feedback!)
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
Heya! We (ReadMe) do indeed work well with Open API specs!
There's definitely alternatives if you're looking to just display docs. But we try to take it a step farther, and make APIs easy to use. We generate code samples in every language, have interactive try-it-now functionality, give you shareable links for API logs, have a nice clean `api` module in certain languages, have a mini getting started guide on each page, and more.
My email is in my profile if you want to talk more! (I'd be curious about any shortcomings you've found we can help out with!)
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:
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:
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 https://stoplight.io/ (using their WebComponent for simplicity). I think I discovered this on the “APIs you won’t hate” podcast.
Actually used them for a short while. I didn't like the additional step in my pipeline to build the docs, also they don't/didn't offer an interactive option. Other than that it looked pretty nice.
Shameless plug: here's my indie-project that converts an OpenAPI/Swagger spec into something that aims to look like Stripe's API Reference:
https://portal.dev
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.
This looks great. But I wish there were a self-hosted version. I work on a project that could use this, but it would really need to be tightly integrated with our existing hosting, I think.
Would it work for you if you could export this as a static website that you could run on your own servers? (you could do that in a Github action), or, alternatively, use some sort of React component that renders the API docs in your app?
I'm considering of making the OpenAPI->API Reference converter an Open Source project, and then charging only if you need advanced features, like wysiwyg/inline editing, change approvals, automatic testing of the examples in the docs etc.
It's just that I'm not sure I can do it until I have these advanced features. If I can't make money out of this I have to return to my day job, and stop developing portal.dev.
22 comments
[ 3.3 ms ] story [ 65.7 ms ] thread(Feel free to shoot me an email if you have any product feedback!)
Any other alternatives to readme.com that look promising?
There's definitely alternatives if you're looking to just display docs. But we try to take it a step farther, and make APIs easy to use. We generate code samples in every language, have interactive try-it-now functionality, give you shareable links for API logs, have a nice clean `api` module in certain languages, have a mini getting started guide on each page, and more.
My email is in my profile if you want to talk more! (I'd be curious about any shortcomings you've found we can help out with!)
https://docs.servicestack.net/api-explorer#api-customization...
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:
https://docs.servicestack.net/api-explorer#api-docs
That for optimal UX all gets bundled together with all the App's components into a single cached download.
I’m also considering schemathesis & fastapi from python.
Here are a couple of example docs: https://space-api.portaldocs.dev (and the OpenAPI behind it: https://github.com/portaldev/nasa-apod-api-docs/blob/main/op...)
https://recur-api-beta.portaldocs.dev
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.
Would it work for you if you could export this as a static website that you could run on your own servers? (you could do that in a Github action), or, alternatively, use some sort of React component that renders the API docs in your app?
It's just that I'm not sure I can do it until I have these advanced features. If I can't make money out of this I have to return to my day job, and stop developing portal.dev.