What is OpenAPI Specification (OAS)?

How it works

Formerly known as the Swagger Specification, OpenAPI allows API developers to define endpoints, HTTP operations, query/path parameters, request bodies, response status codes, error models, and security schemes in JSON or YAML. OpenAPI 3.1 features 100% alignment with JSON Schema Draft 2020-12, enabling full type validation, polymorphic schemas, and automated client SDK generation.

Example

openapi: 3.1.0
info:
  title: Core Account API
  version: 1.0.0
paths:
  /v1/accounts:
    get:
      summary: List account records
      operationId: listAccounts
      responses:
        '200':
          description: Successful array response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'

Common mistakes

• Mixing legacy Swagger 2.0 keywords (definitions, host) with OpenAPI 3.0/3.1 keywords (components, servers)
• Defining non-unique operationId values across paths
• Omitting required properties from the info object block