OpenAPI Specification Reference

OpenAPI 3.x (OAS 3) quick reference: top-level structure, paths, parameters, request bodies, responses, schema objects, components, and security schemes.

Top-Level Structure

Field	Required	Type	Description
`openapi`	yes	string	Version string, e.g. `"3.1.0"`
`info`	yes	Info Object	Metadata about the API (title, version, description)
`servers`	no	Server[]	Array of server base URLs. Defaults to `/`.
`paths`	yes*	Paths Object	Endpoint definitions. *Required in 3.0; optional in 3.1 if webhooks present.
`components`	no	Components Object	Reusable schemas, responses, parameters, security schemes
`security`	no	SecurityRequirement[]	Global security requirements (can be overridden per operation)
`tags`	no	Tag[]	Tag definitions for grouping operations in documentation
`externalDocs`	no	External Documentation Object	Link to additional external documentation

Info Object

Field	Required	Description
`title`	yes	The name of the API
`version`	yes	The API's version string (e.g., `"1.0.0"`)
`description`	no	Short description. Supports CommonMark markdown.
`termsOfService`	no	URL to the Terms of Service
`contact`	no	Contact object with name, url, email
`license`	no	License object with name and identifier/url

Paths & Operations

Each path (e.g., /users/{id}) maps to an HTTP method object:

Field	Required	Description
`operationId`	no	Unique string identifier for the operation. Used by code generators.
`summary`	no	Short (≤120 chars) summary shown in docs
`description`	no	Detailed description. Supports markdown.
`tags`	no	Array of tag strings for grouping in docs UI
`parameters`	no	Array of Parameter or $ref objects
`requestBody`	no	Request body (for POST/PUT/PATCH)
`responses`	yes	Map of HTTP status codes to Response objects
`security`	no	Override global security for this operation
`deprecated`	no	boolean. Marks the operation as deprecated.

Parameter Object

Field	Required	Description
`name`	yes	Parameter name. Case-sensitive for query/header params.
`in`	yes	Location: `path`, `query`, `header`, or `cookie`
`required`	no*	boolean. *Must be `true` for `path` parameters.
`schema`	no	Schema Object defining the parameter type/format
`description`	no	Explains the parameter's purpose
`example`	no	Sample value shown in documentation
`deprecated`	no	boolean. Marks this parameter as deprecated.

Schema Object Fields

Field	Example values	Description
`type`	`string, integer, number, boolean, array, object`	JSON Schema type
`format`	`int32, int64, float, double, date, date-time, uuid, email, uri`	Type hint for serialization
`properties`	Map of field name → Schema	Object properties definition
`required`	`["id", "name"]`	Array of required property names
`items`	Schema Object or $ref	Schema for array items
`enum`	`["asc", "desc"]`	Allowed values list
`nullable`	`true`	OAS 3.0 only — allow null. In OAS 3.1 use `type: ["string", "null"]`
`oneOf / anyOf / allOf`	Array of Schema	Polymorphism: exactly one / at least one / all schemas must validate
`$ref`	`#/components/schemas/User`	Reference to a reusable schema

Security Scheme Types

Type	Key Fields	Description
`apiKey`	`name`, `in: header\|query\|cookie`	Static API key passed in a named header, query param, or cookie
`http`	`scheme: bearer\|basic\|digest`	HTTP auth. bearer = JWT in Authorization header. basic = base64 user:pass.
`oauth2`	`flows` (implicit/password/clientCredentials/authCode)	OAuth 2.0 with defined flows and scopes
`openIdConnect`	`openIdConnectUrl`	Auto-discovery via OIDC well-known URL

Minimal Valid Spec (YAML)

openapi: "3.1.0"
info:
  title: My API
  version: "1.0.0"
  description: A minimal OpenAPI example

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      tags: [users]
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: User not found

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

Validate your OpenAPI spec with the OpenAPI Validator tool.

Frequently Asked Questions

What are the required fields in an OpenAPI 3.x spec?

The minimum required fields are: openapi (version string like "3.1.0"), info (with required sub-fields title and version), and either paths (OAS 3.0) or paths/webhooks/components (OAS 3.1). Each operation's responses field is also required.

What is the difference between parameters and requestBody?

parameters define inputs that come via path, query string, HTTP headers, or cookies — typically used for filtering, pagination, authentication tokens, and path segments. requestBody defines the HTTP request body — used for POST/PUT/PATCH when submitting data as JSON, form data, or file uploads. Only one requestBody is allowed per operation; use it when you need to send structured data.

How do I define a reusable schema in OpenAPI?

Define it under components/schemas and reference it with $ref: "#/components/schemas/YourSchema". For example: define a User schema once under components and reference it from multiple response bodies and request bodies throughout your spec. This avoids repetition and keeps your spec DRY. The same pattern works for parameters (components/parameters), responses, and security schemes.