A URL and a sample response are a useful start to API documentation, but they leave room for assumptions. Suppose a bookstore team documents a catalog endpoint that way. The frontend developer assumes every book has a title, while a partner assumes an unknown book returns an empty object. The server returns an error instead. Each person has read the same documentation, but they have built different expectations.

OpenAPI gives teams a structured way to describe an HTTP API so that people and tools can work from the same interface definition.

This chapter explains what OpenAPI captures, how to read a small description, and where it helps without replacing implementation or engineering judgment.

A successful response shows one possible result. It does not explain every rule a client needs to follow. Consider this response body from a bookstore catalog:

The example leaves several questions unanswered. Are both fields always present? Can title be null? Does the endpoint require credentials? What happens when the identifier has the right shape but no book exists?

An API contract is the set of expectations that clients and servers agree to follow, including accepted inputs, response shapes, and observable behavior. Prose can describe that contract, but teams need a consistent structure if they want software to interpret it.

A machine-readable description makes rules explicit. A tool can read that title is a required string instead of inferring that rule from a sample. The same description can inform a documentation page, a client library, and a test that checks server responses.

This reduces the need to maintain separate copies of the same interface details. It also makes disagreements visible before they become integration failures. If the server team considers a field optional while a client needs it on every response, reviewing the description gives them a concrete decision to resolve.

The OpenAPI Specification (OAS) defines a standard format for describing HTTP APIs independently of their implementation language. An OpenAPI document is a particular API's description in that format. The OpenAPI Initiative maintains OpenAPI.

The distinction matters: the specification defines how to express a response; your document defines the response your service promises.

Documents use YAML or JSON. YAML expresses nested data through indentation and is convenient for examples that people read and edit. Choosing YAML for the description does not require the API to send YAML payloads. A YAML document can describe an API that exchanges JSON, files, or other media types.

OpenAPI can describe public, partner, and internal APIs. The word “open” does not mean the described service is publicly accessible. It also does not certify that an API follows every REST architectural constraint. Its focus is the HTTP interface.

You will also encounter Swagger. OpenAPI grew from the Swagger specification, while the Swagger name remains associated with tools such as Swagger UI, which renders API reference documentation. OpenAPI is the description standard; a documentation renderer is one tool that consumes it.

The diagram shows several uses of one description. Each arrow represents a tool reading the document, not a capability that the document executes by itself.

The benefit comes from sharing interface information across these activities. Their quality still depends on the description and on the tools' support for the features it uses.

Assume the bookstore exposes a public, read-only catalog over HTTPS. Anyone can retrieve a published book by identifier. An unknown identifier returns a bodyless 404 response. These are choices for this example API, not rules OpenAPI imposes.

The following document describes that single operation. An operation is an HTTP method on a particular path, such as GET /books/{bookId}. A schema describes the permitted structure and values of data.

Read this as a description of an HTTP exchange. The server URL and path identify where to send the request. The get entry identifies the method. The path parameter supplies the variable part of the URL. The response entries describe the successful result and the missing-book case.

The schema requires id and title, each with a string value. The example illustrates those rules using one book. It does not restrict all responses to that book's identifier or title. Nor does this schema forbid additional response properties.

The empty security array declares that this API requires no authentication. A private catalog would need a different contract and enforcement in the service.

This example deliberately uses OpenAPI 3.1.2. The openapi value selects the description format; info.version identifies the version of the OpenAPI document, independently of the OAS version. Neither field automatically adds /v1 to a URL or changes server routing. Use a format version that the tools consuming your document support, and check compatibility before changing it.

Here is a request the client sends over HTTPS following the description:

The example below shows a matching successful response. Its body is compact UTF-8 JSON with no trailing newline, matching the stated content length.

An unknown identifier uses the same operation:

Under this API's stated policy, the result is:

Because this operation has no request body, declares no authentication requirement, and imposes no custom identifier pattern, the example does not introduce separate body-validation or permission-error cases. If those requirements become part of the operation, the description must account for their expected failure behavior too.

The document is small enough to review beside these exchanges. That is useful even before introducing generation or automated checks: a reviewer can see that the missing-book behavior is intentional and that clients may depend on both successful response fields.

Writing a rule in OpenAPI does not make a running server obey it. If the implementation returns title: null, the YAML file cannot stop that response from leaving the service. A response validator or a test can detect the mismatch only when someone configures and runs it.

The same boundary applies to security. Describing bearer authentication does not verify tokens. Describing a permission requirement in prose does not check whether the caller owns an order. Application code and infrastructure must enforce those decisions.

OpenAPI also leaves important behavior outside simple structural validation. A schema can require a numeric price, but a structurally valid response may still contain the wrong price for the customer's region. A documented error response does not prove that the service chooses it under the correct conditions.

It helps to separate three kinds of review:

A valid document can still describe a difficult API. It might use confusing names, omit explanations, or demand a long sequence of calls for a simple task. Human design review remains necessary.

Similarly, generated reference documentation explains the available operations, but users may still need a guide explaining how those operations accomplish a business workflow. Keep the narrative and the structured contract consistent; each serves a different reading need.

You can write a description before implementation or generate it from code and annotations. Either approach needs review. A handwritten document can become stale, while a generated one can faithfully reproduce implementation details without capturing the intended business meaning.

Consider a server change that accidentally omits title. The YAML document still parses, and its documentation page still renders. Neither fact reveals the deployed mismatch. A contract check against the changed service can identify that the required field is missing.

The diagram separates checking the description from checking actual behavior:

Each check answers a different question. Validation checks whether tools can interpret the document correctly. Review checks whether the interface expresses the intended design. Testing compares selected service behavior with that agreement.

For a practical starting point, keep the description under version control and include relevant contract changes in implementation reviews. Make it clear which description corresponds to the released API. Otherwise, a correct description of an unreleased feature can still mislead consumers of the current service.

When a mismatch appears, determine which side is wrong. If the implementation accidentally removed title, fix the implementation. If the product intentionally changes its response, evaluate the effect on existing clients before updating the contract. Editing the description merely to make a failing check pass can conceal a breaking change.

Mock responses and generated clients need similar care. A mock can help a frontend developer work before a server exists, but it does not prove that the real service handles permissions or failures correctly. Generated client code can remove repetitive request-building work, but its behavior still needs review and integration testing.

Treat the description as a maintained engineering artifact with an owner and a review process. Its value comes from accurately carrying decisions between people and tools throughout the API's life.

OpenAPI expresses an HTTP API's interface in a standard, machine-readable format. It makes requests, response shapes, and other expectations explicit so that documentation, clients, mocks, and checks can share the same information.

A useful description combines structural rules with clear explanations and realistic examples. It must remain aligned with the service: document validation checks the description, contract tests check selected exchanges, and business tests check behavior that schemas alone cannot establish. OpenAPI supports that work, while design decisions and runtime enforcement remain the team's responsibility.