Validate an OpenAPI Specification

OpenAPI specifications are the industry-standard format for documenting REST API contracts. A valid OpenAPI 3.0 spec file is consumed by a remarkable range of tooling: Swagger UI generates interactive documentation that lets developers explore and test your API directly in the browser; openapi-generator creates type-safe client libraries in dozens of programming languages; API gateways like Kong and AWS API Gateway use specs to configure routing and validation; and mock servers generate fake API responses so frontend developers can work without the real backend being ready. This example shows a minimal but complete OpenAPI 3.0 spec for a users endpoint. The file starts with the required openapi version field, an info block with title and version, then the paths section defining the GET /users endpoint. The endpoint declaration includes a summary, a query parameter definition with its type and default value, a 200 response with a description, and a content type specifying the response schema as an array of User objects defined in the components section. The $ref mechanism is OpenAPI's way of avoiding duplication: instead of repeating the User schema inline in every endpoint that returns user data, you define it once under components.schemas.User and reference it everywhere with $ref: '#/components/schemas/User'. This keeps the spec DRY and ensures all references to User objects are consistent. When you need to update the User schema, you change it in one place. YAML formatting issues in OpenAPI specs are particularly painful because the tools that consume them (swagger-codegen, openapi-generator, Redoc) produce generic parsing errors rather than identifying the specific problematic field. A misindented response code definition or a path that's one space off from its sibling paths will silently fail to render in documentation generators. Real-world scenarios: a team writes the OpenAPI spec before implementation (spec-first design) and shares it with frontend and mobile teams so they can start building against a mock server while the backend is developed in parallel; a CI pipeline validates that the spec is always current with the implementation using spec-testing tools like Dredd. Tips: use YAML anchors and merge keys to share common components like security definitions and error response schemas across many endpoint definitions. Run spectral lint (an OpenAPI linter) after syntax validation to catch semantic issues like undefined $refs and missing required response codes.

openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        email: { type: string }