News for hackers. Stuff that matters.
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 johnx123-up on Tuesday February 08, 2022 @01:41AM (#30255569)
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 wdb on Tuesday February 08, 2022 @08:09AM (#30257914)
Vaguely, I also think it's doesn't support all OpenAPI definition features
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

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.

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 atombender on Tuesday February 08, 2022 @09:38AM (#30258870)
I think ideally a CLI tool to build the static website locally, which can then be deployed anywhere.
Re:Building API Docs by wdb on Tuesday February 08, 2022 @08:08AM (#30257906)
I wish there was an open-source solution something like this or similar to Readme.com but better than Redocly
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:

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.

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 mrbuzzinfrog on Monday February 07, 2022 @09:10PM (#30254151)
Isn't Enunciate only compatible for Java? I like that readme.com uses OpenAPI.

Any other alternatives to readme.com that look promising?

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!)

Re:Building API Docs by mrlatinos on Monday February 07, 2022 @08:39PM (#30253969)
Heroku's API docs made my mobile browser freeze
Re:Building API Docs by faizshah on Tuesday February 08, 2022 @01:28AM (#30255504)
Anyone tried rswag with rails? I’m trying it now.

I’m also considering schemathesis & fastapi from python.