## What makes for good API documentation? - Easy to maintain and keep up-to-date with the latest implementation. Therefore, is ideally auto-generated from a spec such as [[OpenAPI]]. - Provides real-world example data relevant to the domain, not just "foo" and "bar". - Includes detail for error responses as well as happy paths. - Has a "Getting Started" section (independent of the API reference) which helps orient developers in how the API works and how they can set up their environment to consume the API. - Provides a feedback mechanism to report documentation errors or areas for improvement. - Extra nice-to-haves: - Invokeable inline from the docs website ## Examples of good API documentation [[API Design|API]]-based products which have good documentation: - [Spotify API Reference](https://developer.spotify.com/documentation/web-api/reference/#/operations/get-an-artists-albums): ![[SpotifyAPIDocsExample_GetArtistsAlbums.png]] - [Stripe API Reference](https://stripe.com/docs/api) - [APIDocs.io](https://api-docs.io) – Tool which provides "Hosted public API documentation for every OpenAPI Spec and RAML spec out there." --- ## References - [How to Write API Documentation: Best Practices and Examples](https://www.altexsoft.com/blog/api-documentation/)