Re:Building API Docs
by ogazitt on Monday February 07, 2022 @01:59PM
(#30249364)
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.
Re:Building API Docs
by gkoberger on Monday February 07, 2022 @09:14PM
(#30254174)
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!)
Re:Building API Docs
by cplli on Tuesday February 08, 2022 @01:22AM
(#30255476)
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.
Re:Building API Docs
by cplli on Tuesday February 08, 2022 @05:33AM
(#30256856)
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.
Re:Building API Docs
by vrepsys on Tuesday February 08, 2022 @05:33AM
(#30256853)
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.
Re:Building API Docs
by atombender on Tuesday February 08, 2022 @07:05AM
(#30257467)
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.
Re:Building API Docs
by vrepsys on Tuesday February 08, 2022 @07:44AM
(#30257737)
Appreciate the feedback.
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?
Re:Building API Docs
by vrepsys on Tuesday February 08, 2022 @08:15AM
(#30257973)
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.
Re:Building API Docs
by mythz on Monday February 07, 2022 @10:21PM
(#30254555)
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:
Re:Building API Docs
by arcbyte on Monday February 07, 2022 @08:58PM
(#30254079)
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
Re:Building API Docs
by gkoberger on Monday February 07, 2022 @09:28PM
(#30254263)
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!)
(Feel free to shoot me an email if you have any product feedback!)
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.
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.
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!)
I’m also considering schemathesis & fastapi from python.