# OpenAPI / Swagger documentation exists

- **Pattern:** `ab-002213` (`saas-api-design.api-docs.openapi-docs`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002213
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002213)

## Why it matters

Without an OpenAPI spec, every external consumer — a mobile app, a third-party integration, a future backend service — must reverse-engineer your API from network traffic or source code. This directly undermines ISO-25010:2011 compatibility.interoperability and raises integration time proportionally with API surface area. Internal teams suffer the same friction: undocumented APIs attract inconsistent usage patterns and make breaking-change detection impossible without grep-and-hope. A spec is also the prerequisite for automated client SDK generation, contract testing, and mock servers.

## Severity rationale

Low because missing documentation doesn't break runtime behavior, but it compounds integration cost and makes every API change riskier for consumers who can't validate their assumptions.

## Remediation

Generate an OpenAPI spec from your existing Zod validation schemas rather than writing it by hand. If you're already using Zod (recommended), `zod-to-openapi` converts schemas you already have:

```ts
// src/openapi.ts
import { OpenAPIRegistry, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi'

const registry = new OpenAPIRegistry()
registry.registerPath({
  method: 'post',
  path: '/api/v1/users',
  request: { body: { content: { 'application/json': { schema: createUserSchema } } } },
  responses: { 200: { description: 'User created' } },
})
```

Commit the generated `openapi.yaml` to the repo and serve it at `/api/docs` in development. For `ts-rest`, the spec generates automatically from your contract definitions — no extra work.

## Detection

- **ID:** `openapi-docs`
- **Severity:** `low`
- **What to look for:** Count all API routes. Check whether any OpenAPI or Swagger documentation exists. Look for: `openapi.yaml`, `openapi.json`, `swagger.yaml`, `swagger.json` files; packages like `swagger-ui-express`, `@fastify/swagger`, `swagger-jsdoc`, `next-swagger-doc`, `@anatine/zod-openapi`, `zod-to-openapi`, `ts-rest`; a `/api/docs` or `/api/swagger` endpoint; JSDoc `@swagger` annotations in route files.
- **Pass criteria:** At least 1 OpenAPI spec exists (generated or hand-authored) that covers the primary API endpoints. The spec is accessible (served at a URL or committed to the repository).
- **Fail criteria:** No OpenAPI/Swagger documentation of any kind exists.
- **Skip (N/A) when:** The API is entirely internal (only called by the same-repo frontend, no external consumers, no published API). Signal: no evidence of external API consumers, no third-party integrations calling the API, no published API documentation anywhere.
- **Detail on fail:** Example: `No openapi.yaml or swagger.json found`. Note what was found (e.g., "No openapi.yaml, swagger.json, or OpenAPI generation library detected; no /api/docs endpoint"). Max 500 chars.
- **Remediation:** Generate an OpenAPI spec at `src/openapi.yaml` or equivalent from your existing code rather than writing it by hand. If you are using Zod for validation (recommended), use `zod-to-openapi` or `@anatine/zod-openapi` to generate schemas from your existing Zod definitions. For Next.js, `next-swagger-doc` can generate a spec from JSDoc annotations. For `ts-rest`, the spec is generated automatically from your contract definitions. At minimum, commit an OpenAPI YAML file to the repo and serve it at `/api/docs` in development. Even an imperfect spec is better than none — it helps your future self and any collaborators understand what endpoints exist and what they expect.

## External references

- iso-25010 compatibility.interoperability

Taxons: user-experience

HTML version: https://auditbuffet.com/patterns/ab-002213