OpenAPI
A standard, language-neutral format for describing an HTTP API: its paths, operations, parameters, request and response schemas, errors and security.
In more detail
An OpenAPI document is written in YAML or JSON and can be read by people and tools alike: documentation viewers, client generators, mock servers and contract tests. Version 3.1 uses JSON Schema for its data shapes. The older name Swagger survives in some tools.
Example
In this course: Tools can check requests and responses against an OpenAPI document, which gives a schema-based alternative or complement to consumer-driven contracts. It was formerly called Swagger.Related terms
- JSON Schema — A standard vocabulary for describing the allowed shape of JSON data: which fields exist, their types, which are required and what values are allowed.
- OpenAPI components — The section of an OpenAPI document that holds reusable definitions, such as schemas, parameters and responses, referenced from operations.
- design-first — Writing and reviewing an API’s contract, such as an OpenAPI document, before writing the code that implements it.
- contract testing — Testing that an API’s real behaviour matches its written contract, and that its callers only rely on what the contract promises.
- source of truth — The one authoritative place a fact is recorded, from which every copy is derived instead of being maintained separately.
- AddOpenApi — The pair of ASP.NET Core calls that registers built-in OpenAPI document generation (AddOpenApi) and exposes the JSON document as an endpoint (MapOpenApi).
- Scalar — An open-source browser interface that renders an OpenAPI document as interactive API documentation and can send test requests.
- Swashbuckle — A community library that generated OpenAPI documents and the Swagger UI page for ASP.NET Core, included in templates before .NET 9.
- API contract — The written promise an API makes about its operations, inputs, outputs and errors, which callers rely on while the code behind it changes.
- Orval — A tool that reads an OpenAPI document and generates typed TypeScript API clients and TanStack Query hooks.
- code generation — Producing client or server code automatically from a machine-readable contract such as an OpenAPI document or a Protocol Buffers file.
- generated client — Client code produced automatically from an API specification such as an OpenAPI document.
- API — A defined way for one program to ask another program to do something, such as a list of web requests a service accepts.
- schema — A formal description of the structure of data: which fields or columns exist, their types and which are required.
- single source of truth — The one agreed place where a piece of information is maintained, so every copy is generated from it rather than edited by hand.
- contract-driven development — Agreeing on the exact shape of the data two parts of a system exchange first, and building both sides against that agreement.
- SDK — A software development kit: a bundle of tools, libraries and documentation for building software against a platform or service.
Taught in
- Designing Tools A Model Can Use — AI Engineering: LLM Apps, RAG & Agents
- What An API Is, And The Alternatives — Modern API Architecture: REST, GraphQL & gRPC
- OpenAPI And Design-First — Modern API Architecture: REST, GraphQL & gRPC
- Mocking Dependencies — Modern API Architecture: REST, GraphQL & gRPC
- Contract Testing — Modern API Architecture: REST, GraphQL & gRPC
- Security Best Practices — Modern API Architecture: REST, GraphQL & gRPC
- Wikis, Release Notes And Integrations — Microsoft Azure DevOps Engineer Expert (AZ-400) Exam Prep
- Custom Resources And Operators — Certified Kubernetes Application Developer (CKAD) Exam Prep
- Building Routes with Minimal APIs — Modern .NET Core, C# & Enterprise Microservices
- Comparing Controllers and Minimal APIs — Modern .NET Core, C# & Enterprise Microservices
- OpenAPI Generation in .NET 9 — Modern .NET Core, C# & Enterprise Microservices
- API Documentation UI with Scalar — Modern .NET Core, C# & Enterprise Microservices
- API Contract Architecture: OpenAPI 3.1 & Schema Truth — Production Full-Stack Engineering
- Type-Safe Client Generation: Orval & Automated SDKs — Production Full-Stack Engineering
- Type-Safe RPC Architectures: tRPC & Procedures — Production Full-Stack Engineering
- Exception Handling To Problem Details — Modern Java: Virtual Threads & High-Throughput Services
- Implementing An OpenAPI Contract — Modern Java: Virtual Threads & High-Throughput Services
- From Docker To Desired State — Kubernetes: Production-Grade Container Orchestration
- Troubleshooting: describe, Events And A First Smoke Test — Kubernetes: Production-Grade Container Orchestration
- Jobs And CronJobs — Kubernetes: Production-Grade Container Orchestration
- Requests, Limits, Quotas And Horizontal Autoscaling — Kubernetes: Production-Grade Container Orchestration
- A Tiny CRD, Controller And The Operator Pattern — Kubernetes: Production-Grade Container Orchestration
- Contract Testing Between Services — Automated Testing, TDD & Quality Engineering
- Mapped Types, Key Remapping With as And Template Literals — Production TypeScript
- Modern Decorators: Stage 3 Standards And Class Metadata — Production TypeScript
- The Spine Artifact: Generating Typed Models From OpenAPI — Production TypeScript
References
- OpenAPI Specification 3.1.0
- OpenAPI Initiative: What is OpenAPI?
- OpenAPI Specification (latest)
- OpenAPI support in ASP.NET Core API apps
- OpenAPI Initiative