Swagger Docs

OpenAPI 3.0 Documentation

Team standard: OpenAPI Specification 3.0.x OAS 3.1 and 3.2 exist as newer versions with full JSON Schema alignment; migrate when tooling support matures. Rules below are either spec (required by OAS 3.0.x — violations break tooling) or convention (industry best practice from OpenAPI Initiative — violations hurt developer experience).

Core Principle

Documentation is complete when a developer who has never seen the codebase can:

1. Understand what each endpoint does from summary + description alone
2. Know exactly what to send from the request schema + examples
3. Know all possible responses including errors — without asking the implementer

Naming Rules (convention)

Every Operation Must Have (spec + convention)

Schema Rules

• No inline schemas (convention) — define all schemas in components/schemas, reference with $ref
• Every property has description (convention) — explain business meaning, not just the type
• Every property has example (convention) — use realistic data, never "string", 1, or true
• Examples must be valid (spec) — they must conform to the schema (tools use them for test generation)
• Required parameters before optional (convention) — in required array and parameter lists
• Use format (convention) where applicable: email, date-time, uuid, uri, int64
• Document every enum value (convention) — explain what each value means in description

Response Rules

• Document all response codes the endpoint can realistically return
• Every error response includes: machine-readable code + human-readable message
• Reuse error response schema via $ref — consistent shape across all endpoints
• 4xx responses always have an example showing real error payload
• GET endpoints must have at least one 2xx response with content (not just 204)

Reusability Rules (DRY)

• Common responses (401 Unauthorized, 500 Internal Server Error) → components/responses
• Common schemas (error body, pagination, timestamps) → components/schemas
• Common parameters (page, limit, Authorization header) → components/parameters
• Security schemes → components/securitySchemes, applied globally, overridden per-endpoint
• Never repeat the same schema inline in multiple places

File & Structure Rules

• Spec file committed to source control as a first-class artifact (convention — OpenAPI Initiative)
• servers array not empty — include at least production + staging URLs (convention)
• info.contact includes team name or support email (convention)
• info.description explains what the service does and who consumes it (convention)
• Tags defined at root level with descriptions (convention)
• Large APIs (>20 endpoints): split into multiple files using $ref with URL hierarchy (convention)

Quality Checklist

Before finalizing OpenAPI docs:

Structure

• servers is not empty
• info.contact is filled
• All tags defined at root with descriptions
• Spec committed to source control

Operations

• Every operation has summary, description, operationId, tags, security
• operationId is unique, camelCase, under 50 chars
• Required parameters listed before optional

Schemas

• No inline schemas — all in components/schemas
• Every property has description (business meaning, not type restatement)
• Every property has a realistic example
• All examples validated against their schema
• Enums have per-value explanations in description

Responses

• All expected 4xx/5xx documented
• Error responses use consistent shared schema via $ref
• Every error response has a realistic example

Reusability

• Common responses in components/responses
• No duplicated schema shapes — use $ref

Validation Tools

Use these to catch spec errors automatically:

• Spectral (by Stoplight) — linting rules engine, supports custom rulesets
• Swagger Editor — browser-based, real-time validation
• openapi-validator (IBM) — CLI validation
• Integrate into CI: fail PR if spec fails linting rules