OpenAPI / Swagger documentation exists

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.

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:

// 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.

• ID: saas-api-design.api-docs.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.