OpenAPI specification
The OpenAPI Specification is a standard, machine-readable format 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
- Structures REST API descriptions across design, documentation, testing, security checks, implementation, deployment, and consumer integration.
- How deep it goes
- Explains document structure, paths, methods, parameters, bodies, responses, and schemas, while deferring broader advanced OpenAPI layers.
- Examples
- Uses an Online Shopping API with product paths, query parameters, JSON bodies, HTTP responses, and a minimal YAML document.
- What you can do after
- Build it from scratch by authoring an OpenAPI document that communicates and supports an API design.
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
- Describes RESTful API endpoints so tools can display, test, and generate clients for them.
- How deep it goes
- Defines the document’s role and works through generation, metadata, client refresh, and limitations without detailing the full specification schema.
- Examples
- Uses a minimal API with fruit endpoints, Swagger UI requests, endpoint descriptions, and a generated C# client.
- What you can do after
- Operate/configure it with Swashbuckle, inspect it in Swagger UI, and refresh it for NSwag client generation.
Read how ASP.NET Core in Action, 3e 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
- Documents HTTP APIs interactively and supports discovery, implementation alignment, and import into API management.
- How deep it goes
- Explains generation, interactive inspection, metadata, code generation, version overrides, and manager import; defers comprehensive API-design treatment.
- Examples
- Uses FastAPI-generated openapi.json, Swagger Editor, a 3.1.0-to-3.0.0 compatibility fix, and WSO2 API import and deployment.
- What you can do after
- Operate/configure it by inspecting generated definitions, adjusting a reported version, and importing an API into 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 →
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 HTTP services to GPT custom actions by describing how assistants should call their endpoints.
- How deep it goes
- Defines paths, operations, responses, and schemas through a concrete task API, but defers broader API design detail.
- Examples
- Uses a daily tasks endpoint with a Task schema and a GPT task-organizer custom action.
- What you can do after
- Apply it via FastAPI and GPT custom actions to describe, expose, test, and connect an API service.
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.
Related concepts
- Spectralused by · Spectral is an open-source linter that applies configurable rules to JSON, YAML, and structured API description documents.
- 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.
- spreadsheetcontrasts with · A spreadsheet is a grid-based document or application that organizes data in cells arranged by rows and columns and supports calculations.
- 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.
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.