Building API Docs | Hacker News Reader

Building API Docs

brandur.org

86 pointspolyrand18 comments

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 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.

Did you try https://github.com/Redocly/redoc ?

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.

Vaguely, I also think it's doesn't support all OpenAPI definition features

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.

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.

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?

I think ideally a CLI tool to build the static website locally, which can then be deployed anywhere.

I wish there was an open-source solution something like this or similar to Readme.com but better than Redocly

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.

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.

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

Isn't Enunciate only compatible for Java? I like that readme.com uses OpenAPI.

Any other alternatives to readme.com that look promising?

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

Heroku's API docs made my mobile browser freeze

Anyone tried rswag with rails? I’m trying it now.

I’m also considering schemathesis & fastapi from python.

Reply on news.ycombinator.com