OPENAPI

What is OpenAPI Specification (OAS)?

The OpenAPI Specification (OAS) is an open-source, machine-readable standard format for defining, describing, consuming, and visualizing RESTful web services.

Detailed Explanation

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.

Code Example

yaml

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'

Basic OpenAPI 3.1 Specification structure

Common Mistakes to Avoid

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

Validate OpenAPI Specs with APIForge

Paste any OpenAPI specification URL or YAML file into APIForge for instant 0-100 quality scoring, schema linting, and zero-CORS proxy testing.

Try Tool Now →

Share:𝕏 Post in Share

Frequently Asked Questions

What is the difference between OpenAPI and Swagger?

OpenAPI is the open Linux Foundation specification standard, while Swagger refers to SmartBear's commercial and open-source developer toolset (Swagger UI, Swagger Editor).