liminfoOpenAPI Reference
Free reference guide: OpenAPI Reference
About OpenAPI Reference
The OpenAPI Reference covers the full OpenAPI 3.0 specification structure used to describe RESTful APIs. It includes syntax and live examples for every major section: path definitions with HTTP method operations (GET, POST, PUT, DELETE), request body and response schemas, path and query parameters, and security schemes including Bearer JWT, API Key, and OAuth2 authorization code flow.
This reference is particularly valuable for backend developers writing API contracts, frontend engineers integrating with REST APIs, and DevOps teams managing API gateways. The content is organized into six categories — Paths, Schemas, Parameters, Responses, Authentication, and Components — mirroring the actual structure of an OpenAPI YAML document so you can find what you need without switching context.
The Components section covers advanced reuse patterns including $ref references, allOf/oneOf/anyOf schema composition, discriminator for polymorphic models, and reusable parameter and response definitions. Every entry includes a complete YAML example you can copy directly into your API specification.
Key Features
- Full coverage of OpenAPI 3.0 path items: GET, POST, PUT, DELETE with operationId and tags
- Schema definitions with type, format, enum, required fields, and array/object composition
- allOf, oneOf, anyOf schema composition and discriminator for polymorphic types
- $ref references for linking schemas, parameters, and responses across components
- Path, query, and header parameter definitions with required flags and format annotations
- Response definitions with HTTP status codes, content types, response headers, and HATEOAS links
- Security schemes: Bearer JWT, API Key (header/query), and OAuth2 authorization code flow
- Reusable components/parameters, components/responses, and components/requestBodies patterns
Frequently Asked Questions
What is OpenAPI 3.0 and how does it differ from Swagger 2.0?
OpenAPI 3.0 is the successor to Swagger 2.0, introducing a cleaner structure with a unified `components` section for reusable definitions, support for multiple server URLs, a richer `requestBody` field replacing `body` parameters, and improved security scheme definitions including OAuth2 flows. The root key changed from `swagger` to `openapi`.
How do I define a reusable schema component in OpenAPI?
Define schemas under `components/schemas` and reference them with `$ref: "#/components/schemas/YourSchema"`. This allows you to use the same schema in multiple request bodies and responses without duplicating the definition. The same pattern applies to parameters, responses, and request bodies under their respective `components` sub-keys.
What is the difference between allOf, oneOf, and anyOf?
`allOf` means the data must be valid against all listed schemas (used for inheritance). `oneOf` means the data must be valid against exactly one schema (mutually exclusive variants). `anyOf` means the data must be valid against at least one schema (union types). Use `discriminator` with `oneOf` to tell clients which sub-schema to use based on a property value.
How do I add Bearer JWT authentication to my OpenAPI spec?
Define a security scheme in `components/securitySchemes` with `type: http`, `scheme: bearer`, and optionally `bearerFormat: JWT`. Then apply it globally with a top-level `security` array or per-operation. To mark a specific endpoint as public, set `security: []` on that operation to override the global default.
How do I document path parameters in OpenAPI?
Path parameters are declared both in the path string (e.g., `/users/{id}`) and in the `parameters` array with `in: path`, `required: true`, and a `schema` definition. The parameter name in curly braces must exactly match the `name` field in the parameter object.
Can I define examples for request and response bodies?
Yes. You can add an `example` field directly inside a schema definition, or use an `examples` map inside the `content` media type object to provide multiple named examples. The `examples` map approach lets you show different scenarios (e.g., an admin user vs. a regular user response) with summaries and descriptions.
What is HATEOAS and how are links defined in OpenAPI?
HATEOAS (Hypermedia As The Engine Of Application State) is a REST pattern where responses include links to related operations. In OpenAPI 3.0, response `links` allow you to declare that the `id` from a POST response can be used as the `id` parameter in a subsequent GET operation, documenting the relationship between API calls.
How do I use this OpenAPI reference effectively?
Use the category filter to navigate to the section you need — Paths, Schemas, Parameters, Responses, Authentication, or Components. Each entry shows the syntax keyword, a plain-language description, and a complete YAML example. Search by keyword (e.g., "oauth2", "array", "required") to find specific syntax instantly.