OpenAPI Specification Review

Review OpenAPI specification files systematically for standards compliance,
security, API design best practices, and documentation quality.

Input Handling

Determine the input type and gather the specification accordingly:

1. Direct content -- Spec provided inline in the conversation. Review as-is.
2. File path(s) -- Read the specified .yaml, .yml, or .json files.
3. Directory path -- Find all OpenAPI spec files recursively. If multiple
   specs are found, ask the user which to review.
4. URL -- If given a URL, ask the user to provide the file content directly.

Before starting the review phases, determine:

• Format: YAML or JSON
• Version: OpenAPI 2.0 (Swagger), 3.0.x, or 3.1.x
• Structure: Single document or multi-file with $ref to external files

If the spec uses OpenAPI 2.0 or 3.0.x, note version-specific differences and
recommend migration paths to 3.1.x where beneficial.

Review Process

Read references/openapi-checklist.md before
starting the review.

Execute these phases in order. For each finding, assign a severity.

Phase 1: Structural Compliance

Verify the spec conforms to the OpenAPI 3.1 specification structure:

• Required fields -- openapi version string, info.title,
  info.version, and at least one of paths, components, or webhooks
• $ref resolution -- All $ref pointers resolve to valid targets.
  No circular references that would prevent schema validation
• Path templating -- Path parameters match {paramName} syntax and have
  corresponding parameter definitions. No duplicate paths after template
  resolution
• Parameter uniqueness -- Parameters are unique by the combination of
  name and in (location) within each operation
• operationId uniqueness -- Every operationId is unique across the
  entire spec
• Parameter schema -- Parameters use schema for simple values or
  content for complex serialization, never both
• Media types -- Request/response content keys are valid media types
  (e.g., application/json, not invented types)
• Status codes -- Response status codes are valid HTTP codes or default.
  Range codes (2XX, 4XX) used correctly

Phase 2: Security Review

Check security definitions and their application:

• Schemes defined -- At least one security scheme exists in
  components/securitySchemes
• Global or per-operation security -- Security is applied globally or on
  every operation. Flag any operation missing security that does not
  explicitly opt out with an empty array []
• OAuth2 flows -- OAuth2 schemes have valid flow configurations with
  proper authorization and token URLs. Scopes are defined and used
  consistently
• API key placement -- API keys use header or cookie, not query
  (query params appear in logs and browser history)
• HTTPS enforced -- All servers[].url values use https://. Flag any
  http:// URL that is not localhost or 127.0.0.1
• Sensitive data exposure -- Sensitive identifiers (passwords, tokens,
  secrets) are not in path or query parameters. Use headers or request body
  instead
• CORS considerations -- If the API is consumed by browsers, note if
  security-relevant headers are missing from response definitions

Phase 3: API Design Best Practices

Evaluate the API design for RESTful conventions and consistency:

• Resource naming -- Paths use plural nouns (/users, not /user), no
  verbs in paths (/users, not /getUsers), lowercase with hyphens for
  multi-word segments (/user-profiles, not /userProfiles)
• Naming consistency -- Property names follow a single convention
  throughout (camelCase or snake_case, not mixed). Flag inconsistencies
• HTTP method usage -- GET for retrieval (no request body), POST for
  creation, PUT for full replacement, PATCH for partial update, DELETE for
  removal. Flag misuse (e.g., POST for retrieval)
• Pagination -- List endpoints (GET returning arrays) include pagination
  parameters (limit, offset or cursor) and response metadata
• Status codes -- Appropriate codes per method: 201 for POST creation,
  204 for DELETE with no body, 404 documented for resource endpoints, 409
  for conflict scenarios
• Versioning -- Consistent versioning strategy (URL path /v1/, header,
  or query param). Flag mixed approaches
• Component reuse -- Shared schemas, parameters, and responses defined in
  components and referenced via $ref. Flag inline duplication of
  identical or near-identical schemas
• operationId conventions -- operationIds are descriptive and follow a
  consistent pattern (e.g., listUsers, getUserById, createUser)
• Descriptions -- All operations, parameters, and schemas have
  meaningful description fields. Flag missing descriptions on public-facing
  endpoints

Phase 4: Schema and Documentation Quality

Assess schema completeness and documentation:

• Schema completeness -- Schemas define type, use format where
  appropriate (e.g., date-time, email, uri, uuid), set required
  arrays for mandatory properties, define enum for fixed value sets, and
  provide example or examples values
• Discriminator usage -- Polymorphic schemas (oneOf, anyOf) use
  discriminator with a valid propertyName and optional mapping
• Request/response examples -- Operations include example or
  examples in media type objects. Examples are realistic and consistent
  with schema constraints
• Error responses -- 4xx and 5xx responses are defined with consistent
  error schemas (e.g., title, status, detail following RFC 9457
  Problem Details). At minimum, 400, 401, 404, and 500 are documented
• Deprecated operations -- Deprecated operations are marked with
  deprecated: true and their description states the replacement
  endpoint or migration path
• External documentation -- Complex or domain-specific operations link
  to external docs via externalDocs where helpful
• additionalProperties -- Object schemas explicitly set
  additionalProperties to true or false rather than relying on
  default behavior, especially for schemas used in request validation
• String constraints -- String properties define minLength,
  maxLength, or pattern where appropriate to communicate validation
  rules to consumers

Severity Levels

Assign one severity to each finding:

Severity	Label	Meaning
S1	CRITICAL	Spec is invalid, security scheme is missing or broken, or will cause code generation failures. Fix immediately.
S2	HIGH	Likely to cause integration issues, security weakness, or incorrect client behavior. Fix before publishing.
S3	MEDIUM	Design inconsistency, missing documentation, or deviation from best practices. Should be addressed.
S4	LOW	Style suggestion, minor naming improvement, or optional enhancement. Address at discretion.

Output Format

Structure the review as follows:

Summary

Provide a 2-3 sentence overview: what API the spec describes, overall quality
assessment, and the most important finding.

Findings

List each finding with this structure:

[S{n}] {Category}: {Brief title}

• Location: JSON Pointer path (e.g., #/paths/~1users/get/responses) or
  object name
• Issue: What is wrong and why it matters
• Suggestion: Concrete fix, with a YAML or JSON snippet when helpful

Order findings by severity (S1 first), then by location within each severity.

Positive Observations

Note 1-3 things the spec does well. Good component reuse, thorough examples,
or consistent naming deserve acknowledgment.

Summary Table

End with a count table:

Severity	Count
S1 CRITICAL	n
S2 HIGH	n
S3 MEDIUM	n
S4 LOW	n

Guidelines

• Be specific. Reference exact paths, property names, and operationIds.
• Provide concrete fix suggestions with YAML or JSON snippets demonstrating
  the improvement.
• When the spec uses OpenAPI 3.0.x, note 3.1.x features that would improve
  it (e.g., null type support, JSON Schema alignment) but focus the review
  on the version actually used.
• Do not flag valid style choices that are internally consistent (e.g.,
  camelCase vs snake_case is fine if used consistently throughout).
• For large specs (>100 paths), divide the review into logical sections
  (by tag or resource group) and provide a consolidated summary.
• When uncertain about API domain intent, state the assumption explicitly
  rather than making a silent judgment.