The cheat sheet for writing Swagger descriptions
OAS3 specs are full of things that need descriptions. Here are some tips for writing them.
Always start with the action word.
Use the action + object (+ how) pattern consistently for all your descriptions. (Example: "Retrieves a purchase order by ID.")
Write in the present tense
Describe the benefit to the customer, as opposed to implementation.
Be brief
Weak description:
"This API uses the pet ID to compare with IDs in the pet table and then filters results"
This example is not so useful because it describes the implementation, rather than the benefits to the customer.
It also doesn't start with the action word, which makes the reader hunt for the meaning. For the reader, convoluted sentences take a toll when you have to read numerous descriptions to figure out which one does the thing you are looking for.
Better description:
"Finds pets with the ID you searched for."
This example uses the recipe described above. It's brief, starts with the action, and describes the benefit to the customer.
For more about Swagger: “What's missing from your Swagger docs: How to ensure completeness when working with OpenAPI 3."
Coming soon: A deep dive into tool chains
Why is everyone planning to change tools?
Lessons learned about the docs-as-code approach.
How do tool gurus select the right tool for a project?
And more.
If you haven’t subscribed yet, use the subscription box at the bottom of the page to make sure you don’t miss anything.