openapi

OpenAPI description

What it is

An OpenAPI description is a machine-readable document that describes how a web API is meant to be used. It can list available URLs, operations, parameters, request bodies, response shapes, authentication requirements, and example values. It is a contract for API consumers, not the code that actually handles a request.

Why it exists

Without a shared contract, every consumer guesses which URL to call, what data to send, and what response to expect. An OpenAPI description lets documentation tools, client-code generators, test tools, and API Management work from the same agreed API shape.

Key ideas

• A description can say that POST /orders accepts an order body and returns a result. The backend must still implement that behavior correctly.
• OpenAPI documents are commonly written in JSON or YAML. “Swagger” is an older term often used for the tooling and earlier specification name; do not assume every Swagger file uses the same OpenAPI version or feature set.
• A contract should be versioned and reviewed with the API. Changing a required field or response format can break existing clients even if the backend deployment succeeds.
• API Management can import supported OpenAPI descriptions to create or configure an API surface, but importing a document does not automatically make the backend secure, available, or correct.

Northwind example

Northwind publishes an OpenAPI description for its partner order-status API. It documents the URL, required partner token, request parameters, success response, and error responses. The delivery partner generates a client from the contract. When Northwind adds a new optional response field, the partner can usually continue; if Northwind renames a required field, the partner may break unless both sides coordinate a versioned change.

Common confusion

• OpenAPI describes the interface; it is not an API gateway, authentication system, database schema, or runtime.
• A valid document can still describe a poor or insecure API. Test the live behavior against the contract.
• API documentation written only for humans can drift from code. A machine-readable contract can reduce drift but still needs ownership and review.

Related

api-management · api-documentation · api-policies · northwind-traders-case-study

Sources and re-audit

• Microsoft Learn — Azure API Management key concepts, checked 2026-09-16.