What Is the OpenAPI Specification?

The OpenAPI Specification (OAS) is the formal standard for describing HTTP APIs. If What Is OpenAPI explains the concept, this guide explains the actual file structure.

In practice, a specification file is where teams define endpoints, request payloads, responses, authentication, and reusable schemas. The official definition lives in the OpenAPI Specification, while governance is handled by the OpenAPI Initiative. For exact language changes and history, teams often review the OAS GitHub repository.

Treat your OpenAPI file as a product contract, not just documentation.

Core Top-Level Fields

`openapi`

Spec version (`3.0.3`, `3.1.0`).

`info`

Title, version, and description metadata.

`servers`

Base URLs for environments such as prod/staging.

`paths`

Each endpoint and HTTP method definition.

`components`

Reusable schemas, parameters, responses, and security.

`security`

Global auth requirements for protected operations.

Practical Specification Example

This trimmed example shows a clean structure with reusable schemas:

openapi: 3.0.3
info:
  title: Billing API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /invoices/{id}:
    get:
      summary: Get invoice by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Invoice details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
components:
  schemas:
    Invoice:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
        status:
          type: string

Notice how $ref prevents repeating the same response schema in every endpoint.

Reusability with `components` and `$ref`

As your API grows, duplicate schemas become expensive to maintain. Centralize shared definitions inside components, and reference them from paths. If your team uses generated docs, tools such as Swagger UI and Redoc make this reuse visible and easy to verify.

Without Reuse

Same user schema copied in 8 endpoints. One field rename means 8 edits.

With Reuse

Single schema in components/schemas. Changes are made once.

Spec-First vs Code-First

Teams usually follow one of two approaches. In a spec-first approach, the contract is designed first, then implementation follows. In a code-first approach, the service is built first and the spec is generated later.

Spec-First

Better for multi-team collaboration and early API review.

Code-First

Faster for prototypes, but easier to drift from real behavior.

For teams using client generation, spec-first plus OpenAPI Generator usually reduces rework.

Specification Quality Checklist

Every endpoint has success and error responses documented.
Path parameters are required and typed.
Request bodies include required fields and examples.
Operation IDs are unique and stable.
Security is explicit for protected routes.
Spec passes validation before merge.

If you automate these checks in CI, linters like Spectral help enforce consistent rules across repositories.

OpenAPI Specification Explained