OpenAPI Workflow

Scenario

You maintain an API where OpenAPI is part of the contract between backend and client applications.

Changes to endpoints can affect:

• backend validation;
• API documentation;
• generated clients;
• integration tests;
• downstream consumers.

You want coding agents to treat API contract changes as coordinated changes rather than editing only the route implementation.

Repository Structure

api/
├── openapi/
│   ├── openapi.yaml
│   ├── paths/
│   │   ├── users.yaml
│   │   └── projects.yaml
│   └── schemas/
│       ├── user.yaml
│       └── project.yaml
├── src/
│   ├── routes/
│   ├── services/
│   └── schemas/
├── generated/
│   └── client/
├── tests/
│   └── integration/
├── package.json
└── AGENTS.md

AGENTS.md

# Project Instructions

## OpenAPI

- Treat the OpenAPI specification as part of the public API contract.
- Keep implementation and specification changes synchronized.
- Do not manually edit generated client output.

## Endpoint Changes

When adding or changing an endpoint:

- update the relevant OpenAPI path;
- update request or response schemas when required;
- update backend implementation;
- regenerate derived client artifacts;
- update relevant integration tests.

## Compatibility

- Consider existing consumers before removing fields, changing field types, or making previously optional fields required.
- Avoid unrelated breaking contract changes during targeted endpoint work.
- Preserve existing error-response conventions.

## Generation

Use the repository's generation command:

- `pnpm generate:api`

Do not manually reproduce generated files.

## Validation

For API contract changes:

- validate the OpenAPI specification;
- regenerate derived artifacts;
- inspect generated changes;
- run API integration tests;
- run `pnpm typecheck`;
- run relevant consumer tests when practical.

What This Does

This treats the API as more than its route handler.

For example, changing:

POST /users

may involve:

OpenAPI request schema
OpenAPI response schema
backend validation
route/service implementation
generated client
integration tests

These pieces collectively describe the contract.

What This Does NOT Do

The instructions do not say that every internal backend refactor requires an OpenAPI change.

If implementation changes but the external contract remains identical, the specification may not need modification.

For example:

repository refactor
query optimization
internal service extraction

can leave the API contract unchanged.

The file also does not encourage breaking changes merely because updating the specification is easy.

Why These Instructions Matter

Suppose the backend starts returning:

{
  "id": "123",
  "displayName": "Alex"
}

but OpenAPI still declares:

User:
  type: object
  properties:
    id:
      type: string
    name:
      type: string

Now the repository contains two definitions of reality.

Generated clients may still expect:

user.name

while production sends:

user.displayName

Keeping specification and implementation synchronized prevents that drift.

Key Decisions

API contracts have multiple consumers

A contract may be consumed by:

frontend applications
mobile applications
SDKs
partners
tests
documentation

A backend change therefore has a broader impact than its local implementation.

Compatibility should be deliberate

Changes such as:

removing a field
changing a type
making optional data required
renaming an endpoint

can break existing consumers.

Generated clients follow the specification

Do not patch the generated client to compensate for an outdated OpenAPI contract.

Fix the contract.

Validate the specification itself

A valid backend implementation does not guarantee a valid OpenAPI document.

Use the repository's specification validation workflow.

When to Use This Pattern

Use this pattern when:

• OpenAPI describes the application API;
• clients or documentation are generated from it;
• multiple consumers depend on the contract;
• backward compatibility matters;
• endpoint changes regularly affect several artifacts.

The important lesson is:

an API change is a contract change, not merely a route-file change.