OpenAPI
- Category
- Developer tools
- Docs outline
- 16 sections
Official docs outline
spec.openapis.org- Introduction to OpenAPI
What OpenAPI is, API descriptions as machine-readable contracts, tooling ecosystem.
- Structure of an OpenAPI description
Top-level objects: openapi version, info, servers, paths, components, security, tags.
- API endpoints (paths)
Path items, operations per HTTP method, path templating, operationId.
- Parameters
Path, query, header and cookie parameters, serialization style and explode, required.
- Message body content
Request bodies, responses, media types, JSON Schema in schema objects, status codes, examples.
- Reusable components
components section, $ref references, reusing schemas, parameters and responses.
- API servers
Server objects, server variables, base URLs per environment.
- Describing API security
Security schemes (apiKey, http bearer, oauth2, openIdConnect), security requirements, scopes.
- Callbacks
Describing out-of-band requests the API makes to the client's URL.
- Webhooks
Describing event notifications sent by the API provider via the webhooks field.
- Using references
$ref resolution, relative and absolute references, multi-file descriptions, dynamic references.
- Upgrading 3.0 to 3.1
JSON Schema 2020-12 alignment, nullable changes, type arrays, version differences.
- Best practices
Writing maintainable OpenAPI descriptions, design-first vs code-first, organization.
- OpenAPI Specification
The normative OpenAPI Specification: all objects, fields, and rules.
- Overlays
Overlay specification for applying repeatable transformations to an OpenAPI description.
- Arazzo workflows
Describing multi-step API workflows and dependencies across API calls.
Each section links to the official page. Titles and summaries by Extra Credit; the docs belong to their authors.
