Skip to content
BENIBIX Learn

OpenAPI Specification

Development🔌 APIsAPI Design Practices

Also known as OpenAPI, Swagger, OAS, openapi.yaml

One file that lists each path of a REST API and what it sends back.

Think of it like

Think of it like a full menu. It lists every dish and what comes with it.

Example

Emma writes an openapi.yaml for her shop API. A tool turns it into a docs site where partners can try every endpoint.

Why it matters

One file can drive the docs, the tests and the client code, so they never drift apart.

Definition

The OpenAPI Specification is a standard way to describe a REST API in one file. The file is YAML or JSON. It lists every endpoint, what each one takes and what it gives back. Tools read it to make help pages, test the API and write client code. It used to be called Swagger, and many tools still use that name. Writing the file first helps a team agree on an API before coding it.

Example code

yaml
openapi: 3.1.0
paths:
  /books/{id}:
    get:
      summary: Get one book
One endpoint described: GET a book by its id.

Common mistake

Letting the file fall behind the real API. Generate it from the code, or test the code against it.

Key takeaways

  1. 1
    Describes a REST API. Every endpoint and field.
  2. 2
    YAML or JSON. Read by tools.
  3. 3
    Formerly Swagger. Same idea, new name.

Compare