Summary vs description
OpenAPI supports both
description fields and they’re both strings that contain information about the thing they are attached to, such as a parameter, endpoint, schema, or response. So which do you use?
Summary is a plain text field, and should typically be shorter: just one or two sentences. It’s often used when listing elements, although different tools render different tools differently, so always check what your tools product and do whatever looks right there.
Description fields support markdown, so this presents an opportunity to link to additional information or documentation. Particularly in the top-level
info.description field, this can be an opportunity to write multi-paragraph detailed overview documentation.
Good description fields give context
It’s very common to see a description for the
user_id field which says something like “the ID of the user”. Um, thanks?
Everyone can do better than this – and if you’ve ever had to read API documentation from someone else, you know how much difference it makes. I advise people to ask themselves WHAT this field/endpoint/whatever does, and WHY it’s needed. Think about what the user is doing when they use this endpoint, and give a bit more context. Something like “the ID of the user placing the order. This value can be found in the order detail object or order status update object. Find the current user’s ID by going to /user/me`. You get the idea. Context is everything!
Taking pride in API documentation is a Developer Experience multiplier; just make sure that everyone working on your API documentation knows how much you value the extra effort in this area, and that it is something that collaborators should spend time on.
Writing brilliantly is absolutely an art, but writing well enough is attainable for everyone. My advice is always to keep it simple and informative.
* Use short sentences
* Use present tense (the endpoint “does” something, rather than “will do” the thing)
* If you can remove extra phrases, such as “in this case”, do so. It keeps things easier to read
* Be kind. Keep things gender-neutral and inclusive, and avoid belittling words such as “simply” and “just”
With these in mind, you won’t go far wrong. Engineers can absolutely be brilliant at this without formal training.
Markdown in YAML
Description fields support markdown, which is brilliant, and allows expressive additions if you need them. If you use YAML for OpenAPI documents, there are a couple of additional operators that can make it much easier to work with.
Folded block starts with
>. This is great if you just want to wrap your content to make it manageable, or compatible with the linters/formatters you use on the file. I quite like to use a one sentence per line format for markdown, because it makes diffs more readable, and this works nicely with that approach.
description: > This is a folded block style in YAML. It preserves line breaks but ignores leading and trailing white spaces.
Literal block starts with
|. Use this approach if you have markdown that uses whitespace, such as titles or bullet points.
description: | # Title This is some Markdown content. It can include multiple paragraphs, lists, headers, and other Markdown syntax.
Using the appropriate markdown syntax can make things much easier and maintainable over time.
Link to external documentation from API reference
I don’t often see the
externalDocs used but it’s a top-level element in OpenAPI that is designed to make the main API documentation (landing pages, quickstarts, tutorials, etc) easily findable from the API reference documentation. Additionally, OpenAPI tags, schemas and operations all also support
externalDocs properties, so you can link directly to detailed documentation for any of those elements too. Especially useful when there’s a lot of information to include, that can be unwieldy in the description fields.
What are you tips for getting the best documentation from OpenAPI? I’m working full time in this space now (at Redocly, and really enjoying having lots of conversations about docs, APIs, and everything in between!
Also published on Medium.