What's "the right way" to do API documentation these days?

[troyhunt]

Quoting "the right way" as I'm sure there'll be varied opinions, but we need to start rolling this into the new UX:

Should we, for example, go with Swagger: https://swagger.io/solutions/api-documentation/

Something else? Seen something awesome we should be doing? Now is the time to get this right.

[ThisIsMissEm]

Probably OpenAPI v3? It's similar to swagger but more evolved (from what I know of it)

[troyhunt]

That seems to be the most common thread, downloading material to watch on that while I'm travelling 😊

[turegjorup]

OpenAPI v3.x as a baseline. What tools to expose is perhaps more a matter of preference (or they can supplement each other):

• Swagger/OpenAOI editor (classic): https://editor.swagger.io/
• Swagger/OpenAOI editor (next): https://editor-next.swagger.io/
• ReDoc (different renderer for OpenAPI definitions) https://github.com/Redocly/redoc

Personally I like the ReDoc layout better but it lacks the "Try it out" feature of the swagger editor where you can authenticate and do live calls to the API directly from the docs.

Also the Arazzo Specification (part of the OpenAPI Initiative) looks interesting because it

... defines a standard, programming language-agnostic mechanism to express sequences of calls and articulate the dependencies > between them to achieve a particular outcome, or set of outcomes, when dealing with API descriptions (such as OpenAPI > descriptions)".

It's quite new, and I haven't seen it used in the wild yet, so tooling might not be ready. Haven't had time to play around with it.

The value the tools give will be limited by the quality of the OpenAPI specification. So linting that could also be relevant. Tools like https://quobix.com/vacuum/ could be the way to go. Bump.sh has a blog post on how they used to improve their API docs: API Linting with vacuum

[MarkusBiggus]

was hoping @philsturgeon might have a suggestion. He's written some interesting stuff in this space.

[philsturgeon]

Thinking about it just as API docs is a solid way to end up with something that spends a lot of time being out of date, so I try and think of it as a workflow that does loads of handy stuff throughout the api lifecycle. Wrote this guide recently that explains it all for Bump but you can use any docs provider.

https://docs.bump.sh/guides/openapi/specification/v3.1/the-perfect-modern-openapi-workflow/?utm_source=bluesky&utm_medium=social&utm_campaign=modern_openapi_workflow&utm_content=bump

Redoc is good and open source, there’s also Stoplight Element.

Scalar is a more modern popular open source option with a powerful api client built in.

Bump is a solid cheap hosted option.