# OpenAPI Specification

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

**Field:** Software Development  
**Category:** APIs  
**Also known as:** OpenAPI, Swagger, OAS, openapi.yaml

## Think of it like

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

## 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

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

## Example code

```yaml
openapi: 3.1.0
paths:
  /books/{id}:
    get:
      summary: Get one book
```

One endpoint described: GET a book by its id.

## Why it matters

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

## Common mistake

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

## Three principles

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

## Related terms

- [REST API](https://learn.benibix.com/term/development/rest-api)
- [API Endpoint](https://learn.benibix.com/term/development/endpoint)
- [YAML Ain't Markup Language (YAML)](https://learn.benibix.com/term/development/yaml)
- [API Versioning](https://learn.benibix.com/term/development/api-versioning)
- [API Documentation](https://learn.benibix.com/term/development/api-documentation)
- [API-First Design](https://learn.benibix.com/term/development/api-first-design)

## Told apart from

- [OpenAPI vs API Documentation](https://learn.benibix.com/compare/openapi-vs-api-documentation): People think OpenAPI is the docs page, and it is not. OpenAPI is one file that lists each path and reply in a fixed shape, so tools can read it. API docs are the guide people read. A docs page is often built from that file, plus words a person wrote.

---

Source: https://learn.benibix.com/term/development/openapi
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-19
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
