Documenting APIs with OpenAPI

When building an API, documentation almost always feels like something to tackle later. Get it working first, write it up after — but that “after” either never comes, or by the time it does, the code has already moved on. As the gap between the API docs and actual behavior widens, client teams lose their single source of truth.

OpenAPI (formerly Swagger) addresses this directly: define the API as a machine-readable contract. Instead of writing documentation after the code, you either derive it from the code or write the contract first and let the code follow. Both are valid approaches; which one you choose depends on team size and how mature the project is.

Why OpenAPI

The real value of OpenAPI goes far beyond a YAML or JSON file. Once the specification is ready, you can generate client code, write test scenarios, and spin up a mock server. The frontend team can start developing against a server that simulates the real behavior before your API is even implemented.

When working with PHP and Laravel, there are a few mature tools for this. Lately I have been reaching for the dedoc/scramble package. It reads your routes, form request classes, and API resource classes to automatically generate the specification.

composer require dedoc/scramble

After installation, live documentation is immediately available at /docs/api — no additional configuration required.

Anatomy of a specification

An OpenAPI document is built from three core layers: info (API name and version), paths (endpoints and HTTP methods), and components (reusable schema definitions).

openapi: "3.1.0"
info:
  title: "Örnek API"
  version: "1.0.0"
paths:
  /users/{id}:
    get:
      summary: "Kullanıcıyı getir"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: "Başarılı"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

The $ref mechanism is critical here. Instead of redefining the same schema across multiple endpoints, you create centralized definitions. When a schema changes, you update it in one place.

Code-first vs. contract-first

The code-first approach is fast when you need to document an existing API. If the team is small and everyone works in the same repo, auto-generated documentation is often enough. Tools like Scramble automate most of this.

The contract-first approach shows its value when different teams need to work in parallel. You write the OpenAPI file first, and then both the backend and frontend move forward against that contract. There are no surprises at integration time — both sides can progress independently.

I work code-first on personal projects and contract-first on team projects. There is no universally correct answer between the two; the important thing is agreeing with everyone on the team about which approach you are taking.

Versioning and change management

Once an API contract is published, introducing breaking changes affects clients. OpenAPI helps here too: you can diff two versions with tooling and automatically detect what constitutes a breaking change. Tools like oasdiff can plug this comparison directly into your CI pipeline.

In practice, you need a clear rule about when to cut a new version versus extending the existing contract. Additions — new fields, new endpoints — are generally safe; removing things or changing types always requires a version bump.

Keeping the documentation alive

Automatic generation only goes so far. Description text, example values, detailed error responses — these are still content that has to be written by hand. Keeping the documentation complete while keeping the code correct is a matter of discipline.

I have made it a rule during code review: if a new endpoint is added or an existing one changes, leave a note in the PR description about how the documentation should be updated. It feels like a small friction, but it is far less costly than wrestling with incomprehensible docs a few months down the road.

API documentation is always something you look back on and think, “I wish we had done this from the start.” OpenAPI is a mature enough tool to make it practical to start early and at low cost.