Ten Habits for Writing Great OpenAPI Specs

The quality of your generated docs and SDKs is bounded by the quality of your spec. Good news: a handful of habits move the needle more than anything else.

1. Give every operation an operationId

SDK method names are derived from operationId. A clear, verb-first id like listInvoices becomes client.invoices.list(). An unnamed operation becomes a guess. Miss one and the generator falls back to the method and path, which reads like postV1UsersUserIdContact. You can override the name per endpoint in SDK Studio (client shape), but the spec is the better place to fix it.

2. Write real descriptions

Every description field is an opportunity. Compare:

• Get user: technically correct, useless in practice
• Returns the authenticated user's profile, including verified email status: genuinely helpful

3. Use examples liberally

Examples flow straight into docs and playground requests. Provide at least one per request body and response. They land on the generated endpoint pages and in the try-it drawer readers use to call your API from the page.

4. Model errors explicitly

Document the error responses your API returns:

responses:
  "404":
    description: The invoice does not exist.
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Error"

The short list

1. Name your operations
2. Describe everything
3. Add examples
4. Model errors
5. Reuse components with $ref
6. Tag operations into logical groups
7. Mark required fields honestly
8. Prefer enums over free-form strings
9. Version your servers
10. Validate in CI

Treat your spec like source code: review it, lint it, and keep it in version control. Everything downstream inherits its quality.

Run your spec through a linter such as spectral before every merge and the generated output will stay clean automatically.

A few of these have a knob on the Octri side when you can't change the spec at its source. Your tags decide how the SDK groups its methods, so users.list() beats api.users.list(), and both the grouping and the method names are overridable per endpoint in client shape. The docs sidebar can be reordered by hand when the automatic order isn't the story you want to tell. And when the spec itself is the problem and you don't own it, transforms rewrite it before generation. Reach for those second. Fixing the spec fixes every output at once, as generating an SDK spells out.

Starting from scratch? How to generate API documentation from an OpenAPI spec walks the whole pipeline, from writing the spec to hosting docs that update themselves.