Cybersecurity glossary
What is the OpenAPI Specification?
Learn what the OpenAPI Specification is, how it describes HTTP APIs as machine-readable contracts, how tooling uses OpenAPI for docs and gateways, and why accurate specs improve API security.
Definition
The OpenAPI Specification (OAS) is a standard, language-agnostic format for describing HTTP APIs—including paths, operations, parameters, authentication, and schemas—so humans and tools can document, validate, generate, and secure interfaces from a shared contract.
Why OpenAPI matters
HTTP APIs need a shared language beyond wiki pages. The OpenAPI Specification provides that language: a structured contract that documentation portals, code generators, gateways, and security scanners can all consume.
When the contract is accurate, security scales. When it is stale, every downstream control inherits blind spots.
What OpenAPI describes
Operations
Paths, methods, operation IDs, and human summaries for each call.
Schemas
Reusable request/response models with types and constraints.
Security schemes
API keys, OAuth2, HTTP bearer, and per-operation requirements.
Servers and metadata
Base URLs, environments, contact, and version information.
OpenAPI in the delivery pipeline
Author or generate the spec
Design-first YAML or code-first generation produces the OAS document.
Review breaking changes
CI checks compatibility, auth requirements, and sensitive schemas.
Publish for consumers
Developer portals render interactive docs from the same file.
Enforce at runtime
Gateways validate requests against declared parameters and bodies.
Drive security tests
Scanners and contract tests iterate operations for coverage.
Reconcile with reality
Compare observed traffic routes to the published OpenAPI inventory.
Security value vs stale specs
| Practice | Accurate OpenAPI | Stale OpenAPI |
|---|---|---|
| Request validation | Blocks unexpected fields/routes | Allows shadow behavior |
| Auth review | Sees which ops need auth | Misses new sensitive ops |
| Testing coverage | Maps full attack surface | False confidence |
| Partner onboarding | Safe self-service docs | Integrations probe blindly |
OpenAPI security checklist
- Version OpenAPI alongside service code and require review on changes.
- Declare security requirements per operation—not only globally.
- Constrain write schemas; avoid open additionalProperties on sensitive DTOs.
- Use OAS for gateway validation in production where feasible.
- Fail CI when runtime routes diverge from the published contract.
- Mark deprecated operations clearly and track retirement.
- Keep public and internal specs separated by audience.
- Feed OpenAPI into API inventory and security testing pipelines.
The practical takeaway
The OpenAPI Specification is the industry standard contract for HTTP APIs. It is documentation, inventory, validation, and test fuel—if you keep it true.
Treat OpenAPI drift as a security defect, not a paperwork issue.
Related security terms
API Schema
General concept of machine-readable API contracts.
Schema Validation
Enforcing requests against OpenAPI-defined models.
REST API
HTTP API style most often documented with OpenAPI.
API Discovery
Finding APIs that should be represented in OpenAPI catalogs.
Improper API Inventory Management
Risk when OpenAPI catalogs diverge from runtime reality.
Frequently asked questions
What is OpenAPI in simple terms?
It is a standard blueprint file (usually YAML or JSON) that describes an HTTP API so tools can build docs, clients, tests, and gateway rules from the same source.
Is OpenAPI the same as Swagger?
Swagger was the original name. The specification was renamed OpenAPI; “Swagger” often still refers to related tooling.
What does an OpenAPI file contain?
API metadata, servers, paths/operations, parameters, request bodies, responses, reusable schemas, and security schemes.
How does OpenAPI help security?
It enables inventory, request validation, authenticated operation reviews, and coverage-driven testing when kept accurate.
Can OpenAPI describe GraphQL?
OpenAPI targets HTTP resource APIs. GraphQL typically uses its own schema language, though HTTP metadata can still be noted.
Should OpenAPI be generated or hand-written?
Both work. Design-first writing improves review; generation from code must be gated so drift and over-permissive models are caught.
What if the spec is wrong?
Gateways and scanners trust a fiction. Runtime shadow endpoints and undeclared fields become invisible to controls.
References
Explore authoritative guidance and frameworks related to openapi specification.
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.