OpenAPI is an open format for describing REST and REST-like APIs. An OpenAPI document records resource paths, HTTP operations, inputs, outputs, and data models in a machine-readable blueprint. It replaces fragile spreadsheets or prose documents with a shared artifact for design, discussion, documentation, testing, security checks, and generation. section 6.1.1 section 6.0
Use OpenAPI to connect API design decisions with implementation and consumer experience:
- Describe the programming interface while designing HTTP operations and data models, rather than beginning with OpenAPI during needs analysis. section 6.1.5
- Make stakeholder discussions concrete through human-readable summaries and descriptions that explain paths, operations, request data, and responses. section 6.4.2 section 6.9
- Generate documentation, mocks, tests, implementation code, security checks, API-gateway configuration, and other lifecycle artifacts from the same description. section 6.1.1 section 6.1.2
- Reduce repetition by defining reusable schemas, parameters, and responses after the initial interface design is stable. section 6.1.2 section 6.1.5
Online Shopping API
A minimal YAML document can begin with `openapi: 3.1.0`, an `info` object containing the API title and version, and a mandatory `paths` object. Add `/products` with the summary `Catalog`, then place lowercase HTTP methods beneath it: `post` for adding a product and `get` for searching products. Define search inputs such as `keywords` and `category` in `parameters` with `in: query`; describe a product payload under `requestBody` with `application/json`; and describe `201`, `400`, and `500` responses under `responses`, each with its status description and content. section 6.4.1 section 6.5 section 6.6.1 section 6.6.2
Choose the authoring approach according to context: specification-first authoring is usually recommended, while code-first generation can be appropriate. Write documents in JSON or YAML; YAML is often easier for humans to read and comment on, but indentation errors can be troublesome. Prefer OpenAPI 3.1 when compatible tooling supports it. OpenAPI 3.0 remains acceptable for broader tool support, while 2.0 support is declining. section 6.2 section 6.2.4 section 6.2.5
Listing 6.1 A minimal OpenAPI document
openapi: 3.1.0 #1
info: #2
title: Online Shopping #3
version: "1.0" #4
paths: {} #5
Use the minimal-document listing as a starting template before adding paths, operations, inputs, outputs, and schemas. section 6.4.1
