How to Write a Lint-Clean OpenAPI 3.0 Specification

Tested against Redocly lint (0 errors/warnings) and Spectral. Last updated 2026-08-24.

Most auto-generated OpenAPI files fail lint with dozens of warnings: missing examples, untyped error responses, operationId collisions, and additionalProperties left open. Buyers and internal platform teams reject specs that don't pass redocly lint. Here is the checklist we use to ship a clean openapi: 3.0.x document every time.

1. Pin the version and info block

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
  description: Short, useful summary.

2. Every path needs operationId, tags, and a response schema

paths:
  /users/{id}:
    get:
      operationId: getUserById
      tags: [users]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
        '404':
          description: Not found
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Error' }

3. Define reusable schemas with examples

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id: { type: string, example: "usr_01H" }
        email: { type: string, format: email, example: "a@b.com" }
    Error:
      type: object
      required: [error, message]
      properties:
        error: { type: string, example: "not_found" }
        message: { type: string, example: "User not found" }

4. Lint it

npx @redocly/cli lint openapi.yaml
# or
npx @stoplight/spectral-cli lint openapi.yaml

A clean run prints openapi.yaml: passed with no warnings.

← Back to articles