API routes or public interfaces are documented

Undocumented API routes are a maintenance hazard: a developer adding a new caller must read the full implementation to understand the expected request shape, authentication requirements, and error responses. At scale, this creates integration bugs and prevents safe independent development. ISO 25010 maintainability.analysability and reusability both degrade. Projects with 10+ API routes and zero documentation force every integration point to be reverse-engineered from implementation details — the kind of friction that produces subtle API misuse bugs.

Add a brief comment block to each API route describing its purpose, accepted input, and response shape:

// app/api/submissions/route.ts
/**
 * POST /api/submissions
 * Accepts an audit_telemetry JSON payload, validates schema,
 * computes scores, and stores in the submissions table.
 *
 * Body: AuditTelemetryPayload (see lib/types/telemetry.ts)
 * Returns: { submission_id: string, score: number }
 * Errors: 400 (invalid payload), 422 (validation failed)
 */
export async function POST(req: Request) { ... }

For larger APIs, generate an OpenAPI spec from your Zod schemas using zod-to-openapi — you get documentation and runtime validation from a single source of truth.

• ID: code-maintainability.documentation.api-documented

• Severity: medium

• What to look for: Check for API route handlers in app/api/ or pages/api/. For each route handler, look for:

  • A comment at the top of the file describing what the endpoint does, expected input shape, and response shape
  • JSDoc on the handler function
  • An OpenAPI/Swagger spec file (openapi.yaml, swagger.json, or similar)
  • A docs/api.md or similar documentation file

  Also check exported library functions (if project type is library) for JSDoc documentation. For projects with no API routes, check whether exported utilities/hooks have any documentation.

• Pass criteria: Count all API route files in the project. Either: an OpenAPI/Swagger spec exists covering the API, OR at least 70% of API route files have a comment or JSDoc describing the endpoint's purpose and input/output shapes. Report the ratio: "X of Y API route files are documented."

• Fail criteria: The project has 3+ API routes, none of which have any documentation or comments describing their purpose or expected inputs/outputs.

• Skip (N/A) when: No API routes detected and project type is not a library. Signal: no app/api/ directory, no pages/api/ directory, no exported functions in a library-style package.json.

• Detail on fail: "12 API route files in app/api/ — none have comments describing expected input, output, or purpose. A new developer must read the full implementation to understand what each endpoint does."

• Remediation: Even brief inline documentation on API routes saves significant time during debugging and onboarding:

  // app/api/submissions/route.ts
  /**
   * POST /api/submissions
   * Accepts an audit_telemetry JSON payload, validates schema,
   * computes scores, and stores in the submissions table.
   *
   * Body: AuditTelemetryPayload (see lib/types/telemetry.ts)
   * Returns: { submission_id: string, score: number }
   * Errors: 400 (invalid payload), 422 (validation failed), 500 (storage error)
   */
  export async function POST(req: Request) {
    // ...
  }
  

  For larger projects, consider generating an OpenAPI spec from your code using zod-to-openapi or similar tools — you get documentation and type safety from a single source.