I love documentation, which is supposed to be rare for software engineers. I am pretty sure that loving documentation is actually very common, but not very cool and so few people admit to it! I love reading good docs, and so I love writing them too. Between hanging out in the Write the Docs community, and recently being at the APItheDocs conference, I’ve answered a bunch of questions about getting good documentation from an OpenAPI document, so I thought I’d round them up in case it’s useful.

Summary vs description

OpenAPI supports both summary and 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.

Simplest styleguide

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!