How to Write a Good Swagger

good-bad-swagger.md

Don't and Do in OpenAPI / Swagger

If your API spec needs explanation, it's already broken.

OpenAPI has shaped the landscape of web services. With its simple and intuitive declarative syntax, a wide range of tools that can generate Swagger from code, and numerous solutions for hosting, sharing, and collaborating on interface specifications, it has become a standard in the IT industry.

But knowing how to use the tools isn’t enough. While creating a Swagger file is easy, writing one that serves as meaningful documentation requires copywriting skills, attention to detail, and the ability to anticipate all possible usage scenarios.

In this short memo, you’ll find simple, actionable advice on how to turn your OpenAPI spec into a document that provides real value — whether you’re building the service or consuming it.

Rule 1: Always provide meaningful and complete operation descriptions

Don’t just restate what the route does — explain the operation's purpose, context, preconditions, and invariants.

❌ Don't

POST /documents
description: "Create document"

(This merely echoes the route name and adds no value.)

✅ Do

POST /documents
description: >
  Create a document in the specified collection.
  If no document ID is provided, one will be generated automatically by the service.
  The created document will be assigned the status DRAFT.

Rule 2: For status codes, describe when they are returned — not what they mean in HTTP

Avoid restating the HTTP standard. Instead, describe the functional conditions that lead to the response.

❌ Don't

400 – Bad Request

✅ Do

400 – Invalid input. This may include cases such as fewer than two input fields provided, invalid email format, invalid phone number, invalid fidelity card number, or unknown product category.

Rule 3: Always provide realistic examples

Avoid placeholder strings like "string". Use meaningful, real-world data to help developers understand the format and intent.

❌ Don't

// example

{
  "name": {
    "firstName": "string",
    "lastName": "string"
  },
  "email": "string",
  "phone": {
    "prefix": "string",
    "number": "string"
  }
}

✅ Do

// example

{
  "name": {
    "firstName": "Alice",
    "lastName": "Dupont"
  },
  "email": "[email protected]",
  "phone": {
    "prefix": "+33",
    "number": "612345678"
  }
}

Rule 4: Use enum types when a field has a known, finite set of values

This improves validation, readability, and tooling support.

❌ Don't

productCategory: string
example: "TOY"

✅ Do

productCategory:
  type: string
  enum: [TOY, CLOTHES, FOOD]
  example: TOY

Rule 5: Always document the expected format of inputs and values

Every attribute, parameter, or field that follows a standard format should include an explicit description of that format.

❌ Don't

phone:
  description: Phone number

✅ Do

phone:
  description: Phone number starting with a `+` followed by the country code and number, with no spaces or separators.

Rule 6: Prefer long, descriptive names

When naming attributes, parameters, or fields, always aim for specificity. Favor long, precise terms over short, ambiguous ones.

❌ Don't

parameter: "phone"

(The word “phone” could refer to a phone number, a device, or even a phone type — it’s too vague.)

✅ Do

parameter: "phoneNumber"

(This makes the intent clear and unambiguous.)

Other Advice

1. Make your Swagger specification explicit enough that the reader won’t need to contact you to understand its meaning.
2. Anticipate edge cases and describe them clearly using appropriate HTTP status codes.
3. Keep your naming consistent across all endpoints of the service. If one endpoint uses a field called productName, don’t switch to product in another — reuse the exact same term.