3 ms·
UK Government Guidelines on Documenting APIs
- kh1 4y agoThis looks great, but many orgs use auto-generated documentations for client libraries (e.g. OpenAPI), which IMO doesn't give you easy-to-understand introduction/overview. And I've seen many documentation I have to decipher. Although tools like OpenAPI has its own place when it comes to documentation, should we maintain "intuitive" end-user documentation separately? I don't think this can be automated based on the code.
- eropple 4y agoI own server API SDKs at Mux, and we use OpenAPI to drive our generated ones. If you use OpenAPI and generate client SDKs from it (rather than expecting end consumers to do so -- there are usually enough rough edges in the base SDK that I find it worth doing so) it's pretty easy to pack these in by editing the README templates on a per-platform basis or the like.
- moaf 4y ago> Should we maintain "intuitive" end-user documentation separately? The answer is a resounding “yes”. Definitions are an important part of API documentation, but user guides and tutorials are equally important if you really want to empower developers. OAS really doesn’t support much additional information outside of definitions and simple descriptions, so complimentary documentation is often needed.
- spansoa 4y ago> what your API does and does not do This could mean specifying a LOT of things that an API cannot do, but it's easier to state what an API can't do rather than list all its capabilities, similar to how people can list 100s of negative emotions and fail bad at specifying lots of positive emotions.
- jollygoodshow 4y agoI don't think they expect you create an exhaustive list of things the API doesn't do. I think instead that if there's missing functionality from what you could call a 'complete' API, it's useful to call that out. E.g this API is for processing images, but we don't support PNG