OpenAPI specification
The OpenAPI Specification is a machine-readable standard for describing HTTP APIs, including their operations, inputs, outputs, data structures, and security requirements.
Automating API Delivery
The OpenAPI Specification is a standard machine-readable format for describing HTTP APIs, including their operations, inputs, and responses.
- How it is used
- Provides a shared API contract for design-first delivery, governance, implementation checks, and published reference documentation.
- How deep it goes
- Defines the standard and definition-file distinction, illustrates document hierarchy, and follows operational workflows rather than specifying every OAS field.
- Examples
- Uses a missing mandatory response field, a changed catalog endpoint, Spectral editor feedback, and regenerated API reference documentation.
- What you can do after
- Apply it via Git-based reviews, Spectral linting, conformance checks, and generated documentation to keep an API definition useful through delivery.
Read how Automating API Delivery explains OpenAPI specification →
The Design of Web APIs, Second Edition
OpenAPI 3.1 is a version of the OpenAPI standard that adds support for a more recent JSON Schema version and webhooks.
- How it is used
- Describes a REST API’s HTTP interface during design and provides a standard description usable across API lifecycle tools.
- How deep it goes
- Works from a minimal document through paths, operations, parameters, bodies, responses, and schemas, while deferring some design and advanced features.
- Examples
- Uses shopping catalog paths and product operations, plus a music-streaming API call to practice describing an interface.
- What you can do after
- Build it from scratch: author an OpenAPI document for resource paths, HTTP operations, inputs, outputs, and data models.
Read how The Design of Web APIs, Second Edition explains OpenAPI specification →
ASP.NET Core in Action, 3e
An OpenAPI document is a structured document that describes an HTTP API's available URLs, operations, parameters, and data types according to the OpenAPI standard.
- How it is used
- Uses OpenAPI documents to expose minimal API descriptions for testing and client generation.
- How deep it goes
- Explains document generation, endpoint metadata, client refresh, and limitations through practical setup steps.
- Examples
- Uses a fruit-stock minimal API with GET and POST endpoints and a generated C# client.
- What you can do after
- Apply it via Swashbuckle, Swagger UI, and NSwag to document and test endpoints and generate a C# client.
Read how ASP.NET Core in Action, 3e explains OpenAPI specification →
Microservices Patterns, Second Edition
A standard for describing HTTP APIs, including their operations, parameters, and schemas, in a machine-readable format.
- How it is used
- Defines machine-readable REST API contracts for design, documentation, and governance.
- How deep it goes
- Describes contract fields, generation options, and tool uses without detailing document syntax.
- Examples
- Uses a Spring Boot service with controller annotations and SpringDoc OpenAPI to illustrate document generation.
- What you can do after
- Apply it via SpringDoc OpenAPI to generate a contract from Spring Boot controllers and annotations.
Read how Microservices Patterns, Second Edition explains OpenAPI specification →
Build Financial Software with Generative AI (From Scratch)
An OpenAPI definition is a machine-readable description of an HTTP API's available operations, inputs, outputs, and metadata.
- How it is used
- Supports API discovery, interactive documentation, and generation of client and initial server code.
- How deep it goes
- Walks through generated definitions, editor inspection, manager import, and version configuration, while noting that additional OpenAPI features remain unexplored.
- Examples
- Uses a FastAPI file API, Swagger Editor, and a WSO2 import to demonstrate a generated definition.
- What you can do after
- Operate and configure a generated OpenAPI definition using FastAPI, Swagger Editor, and WSO2.
Read how Build Financial Software with Generative AI (From Scratch) explains OpenAPI specification →
Secure APIs
OpenAPI is a standard format for describing HTTP APIs, including their operations, parameters, request bodies, responses, and security requirements.
- How it is used
- Documents API design and security decisions, then guides implementation and contract testing.
- How deep it goes
- Explains specification structure and security application, with YAML examples; defers broader endpoint modeling details.
- Examples
- Uses a ride-sharing API, JWT bearer YAML, global security, public endpoints, and contract-testing fuzzers.
- What you can do after
- Configure API security by declaring schemes and applying authentication requirements globally or per operation.
Building Web APIs with ASP.NET Core
The OpenAPI specification is a machine-readable standard for describing HTTP APIs, including their operations, inputs, and outputs.
- How it is used
- Documents RESTful web APIs automatically so clients and developers can understand and interact with available endpoints.
- How deep it goes
- Defines the contract and connects it to generated documents and interactive tooling through ASP.NET Core integration.
- Examples
- Uses Swashbuckle, swagger.json, SwaggerUI, endpoint descriptions, parameters, responses, and request-response samples.
- What you can do after
- Operate Swashbuckle to generate, inspect, test, and customize an OpenAPI description for an ASP.NET Core API.
Read how Building Web APIs with ASP.NET Core explains OpenAPI specification →
.NET in Action, Second Edition
OpenAPI is a machine-readable specification for describing HTTP APIs, including their endpoints, operations, parameters, and representations.
- How it is used
- Deploys OpenAPI through Swagger UI to test HTTP API operations directly from a browser.
- How deep it goes
- Explains terminology and configures document generation and UI exposure, but does not descend into the OpenAPI specification format.
- Examples
- Uses Catalog API GET, POST, PATCH, and DELETE operations as interactive testing examples.
- What you can do after
- Operate/configure it through Swashbuckle and Swagger UI to generate API documentation and send test requests.
Read how .NET in Action, Second Edition explains OpenAPI specification →
Spring Start Here, Second Edition
OpenAPI is a standard, machine-readable specification format for describing HTTP APIs, including their operations, inputs, and responses.
- How it is used
- Uses an API contract to generate endpoint code and support consistent implementations, cross-team sharing, and automatic documentation.
- How deep it goes
- Defines the contract-first workflow and shows an endpoint example, but defers detailed OpenAPI instruction.
- Examples
- Describes a payment endpoint with a POST operation, request body, response, and PaymentDetails schema.
- What you can do after
- Understand how a contract-first workflow can generate endpoint code and documentation from an API description.
Read how Spring Start Here, Second Edition explains OpenAPI specification →
LLMs in Production
OpenAPI is a specification standard for describing HTTP APIs so that their operations, inputs, outputs, and security requirements can be understood by tools and clients.
- How it is used
- Standardizes API descriptions so tools, clients, and LLM integrations can discover and consume HTTP APIs.
- How deep it goes
- Defines the standard’s role and integration workflow but does not detail its schema or implementation.
- Examples
- Uses an OpenAPI config file, ai-plugin.json, hosted APIs, and ChatGPT plugin registration as concrete integration artifacts.
- What you can do after
- Apply it via an OpenAPI configuration to make an API easier for external tools and clients to consume.
Read how LLMs in Production explains OpenAPI specification →
AI Agents in Action
An OpenAPI specification is a machine-readable standard description of an HTTP API's endpoints, operations, parameters, and data structures.
- How it is used
- Connects an assistant to an external API by supplying its machine-readable definition as a custom action.
- How deep it goes
- Demonstrates a generated endpoint specification down to paths, response schemas, and data fields.
- Examples
- Uses a GET /tasks endpoint whose response contains task IDs, descriptions, and completion states.
- What you can do after
- Apply it via GPT custom actions by configuring a service specification and testing the resulting connection.
Read how AI Agents in Action explains OpenAPI specification →
Contract Testing in Action
OpenAPI is a standard, human-readable specification for describing the structure and behavior of HTTP APIs.
- How it is used
- Coordinates frontend and backend API development and supplies inputs for documentation, mocks, integration tests, and contract tests.
- How deep it goes
- Defines endpoints, parameters, responses, schemas, and examples, but stops short of automatically preventing integration bugs without contract-test enforcement.
- Examples
- Uses user and movie endpoints, Express-generated JSON, Dredd configuration, endpoint execution, and Markdown test reports.
- What you can do after
- Apply it via Dredd or another API testing tool to verify documented provider interactions before deploying changes.
Read how Contract Testing in Action explains OpenAPI specification →
Software Testing with Generative AI
OpenAPI is a standard for describing HTTP APIs and their operations, data structures, and constraints in a machine-readable format.
- How it is used
- Uses API schemas to constrain prompts for rapid generation of structured test data.
- How deep it goes
- Demonstrates schema-guided JSON generation and validation, but does not explain OpenAPI semantics beyond data constraints.
- Examples
- Uses a Room schema, a three-object JSON-generation prompt, and generated hotel-room records.
- What you can do after
- Apply it via prompts to generate structured JSON test data and check outputs against declared schema rules.
Read how Software Testing with Generative AI explains OpenAPI specification →
Quarkus in Action
OpenAPI is a standard machine-readable description of an HTTP API's operations, parameters, and responses.
- How it is used
- Describes REST resources in a machine-readable form and supports interactive HTTP API testing through Swagger UI.
- How deep it goes
- Explains generated metadata, operations, payload schemas, and responses, but defers document customization.
- Examples
- Uses a reservation service with POST and GET operations, Reservation schemas, JSON payloads, and available-car responses.
- What you can do after
- Operate/configure Quarkus endpoints through generated OpenAPI documents and Swagger UI, including production UI availability.
Also covered in
- API Design Patterns
- Pro ASP.NET Core 7, Tenth Edition
- Effective Conversational AI
- Build AI-Enhanced Web Apps
- Grokking Software ArchitectureIn early access (MEAP)
What to know first
- RESTREST is an architectural style for distributed systems that organizes interactions around identifiable resources and their representations, using a uniform interface and constraints such as statelessness and cacheability.
- contractA contract is an agreed specification of the conditions, expectations, rights, or obligations that govern behavior or interactions between parties or software components.
- JSONJSON is a language-independent text-based data-interchange format that represents structured values using objects, arrays, strings, numbers, booleans, and null.
- authenticationAuthentication is the process of verifying the claimed identity of a user, service, device, or other entity.
Related concepts
- api lintingused by · API linting is the automated analysis of an API description or design against rules for correctness, consistency, security, and maintainability.
- JSON Schemauses · JSON Schema is a standard vocabulary and specification for describing, validating, and annotating the structure and constraints of JSON data.
- Spectralused by · Spectral is an open-source linter that applies configurable rules to JSON, YAML, and structured API description documents.
- code-first approachproduced by · A code-first approach defines a system, model, or contract in source code before deriving or finalizing its schema or specification.
- provider-driven contract testingused by · Provider-driven contract testing is a contract-testing workflow in which the provider determines or contributes the contract expectations and compares them with consumer expectations.
Questions about OpenAPI specification
What is OpenAPI specification?
The OpenAPI Specification is a machine-readable standard for describing HTTP APIs, including their operations, inputs, outputs, data structures, and security requirements.
Which Manning books explain OpenAPI specification?
Automating API Delivery, The Design of Web APIs, Second Edition, ASP.NET Core in Action, 3e, Microservices Patterns, Second Edition, Build Financial Software with Generative AI (From Scratch), Secure APIs, Building Web APIs with ASP.NET Core, .NET in Action, Second Edition and 6 more.
What should I know before learning OpenAPI specification?
Manning books that teach OpenAPI specification usually introduce REST, contract, JSON and authentication first.
What are the parts of OpenAPI specification?
OpenAPI specification includes paths object.
What is OpenAPI specification also called?
OpenAPI specification is also called Swagger Specification, Open API or OpenAPI format.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.













