What spec-first means

Define the OpenAPI (Swagger) specification before writing any implementation code. The spec is reviewed, approved, and frozen first. Code is generated or written to match it.

Benefits

  • Frontend and backend teams can work in parallel — frontend mocks from the spec.
  • Breaking changes are caught in spec review, not in production.
  • Documentation is always accurate — it is the spec, not retrofitted docs.
  • SDK generation is trivial: openapi-generator produces clients in 40+ languages.

Tooling

  • Stoplight Studio — visual spec editor with validation.
  • Spectral — lint OpenAPI specs against custom style rules in CI.
  • Prism — mock server from spec, used by frontend before backend is built.
  • openapi-generator — generate server stubs and client SDKs.

Minimal OpenAPI example

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{id}:
    get:
      summary: Get order by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Order found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }