OpenAPI Validator

The OpenAPI Specification: from Swagger to OpenAPI 3.1

The OpenAPI Specification (OAS) is the most widely adopted standard for describing HTTP APIs. It started in 2010 as Swagger, became an open standard in 2015 when SmartBear donated the work to the Linux Foundation, and is now stewarded by the OpenAPI Initiative. Versions in the wild: Swagger 2.0 (legacy, still common), OpenAPI 3.0 (modular, 2017) and OpenAPI 3.1 (current, 2021), which finally aligns with JSON Schema Draft 2020-12.

A valid spec is a YAML or JSON document that fully describes endpoints, methods, parameters, request bodies, response shapes, security schemes and servers. From that single source you can generate interactive docs, server stubs, client SDKs, mock servers, contract tests and linting rules.

Anatomy of an OpenAPI document

Top-level keys required or recommended on every spec:

• openapi — the spec version (3.0.3, 3.1.0).
• info — title, version, description, license and contact for the API.
• servers — base URLs (production, staging, sandbox) with optional variables.
• paths — the catalog of URL routes; each path maps HTTP methods to operations.
• components — reusable schemas, responses, parameters, requestBodies, securitySchemes, examples, headers.
• security — applied globally or per-operation; references the schemes under components.
• tags — group operations in the rendered docs.

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by id
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:    { type: string, format: uuid }
        email: { type: string, format: email }

Tooling: docs, editors, validators, codegen

• Swagger UI — interactive API explorer with "Try it out" calls; the original Swagger product.
• Redoc — beautiful read-only three-pane docs, good for public references.
• Stoplight Studio and Insomnia Designer — visual editors that round-trip YAML/JSON.
• swagger-parser (Node) and openapi-validator (IBM) — schema + reference resolution.
• Spectral (Stoplight) — the de facto OpenAPI linter; rulesets enforce naming, tag coverage, response codes.
• openapi-generator — generates client SDKs and server stubs in 40+ languages from the spec.
• Prism and Stoplight mock — instant mock servers driven by examples in the spec.
• Postman and Insomnia — import OpenAPI to build collections automatically.

OpenAPI vs API Blueprint, gRPC, AsyncAPI

• vs API Blueprint — Apiary's Markdown-based format; discontinued in practice as OpenAPI won the ecosystem race.
• vs gRPC + Protobuf — gRPC uses binary HTTP/2 framing and Protobuf IDL for service-to-service traffic; OpenAPI describes textual HTTP/JSON APIs for public consumption.
• vs AsyncAPI — the same idea, but for event-driven systems (Kafka, RabbitMQ, MQTT, WebSocket). Many teams ship both.
• vs GraphQL SDL — different paradigm (single endpoint, typed query language). OpenAPI describes RESTful semantics.

API-first design and the Brazilian Open Banking

API-first is a workflow where you write the OpenAPI spec before any code, run it through Spectral and review it in a pull request. From the approved spec you generate client SDKs, server stubs and mock servers; backend and frontend teams develop in parallel without blocking each other.

In Brazil, the public sector adopted OpenAPI in force. Receita Federal, Banco Central and the entire Open Finance Brasil (formerly Open Banking BR) ecosystem publish OpenAPI 3.x specs. Open Finance Phase 4, in production since 2022, standardizes the APIs through which banks share customer data and initiate payments — every certified participant exposes endpoints that match the official spec exactly, validated by automated test suites.

Best practices that move the needle

• Tag operations — Swagger UI and Redoc use tags to group endpoints; without them documentation is a flat list.
• Provide examples on every request body and response — they feed mock servers, SDK tests and clients.
• Declare every error response — 400, 401, 403, 404, 422, 429, 500; clients code defensively against them.
• Use security schemes — oauth2 with flows, apiKey in header, http: bearer; reference them at the operation level.
• Reuse schemas via $ref — Money, Address, Pagination types deserve their own component.
• Lint with Spectral in CI — enforce naming, response coverage, casing and documentation completeness.

FAQ

Should I write Swagger 2.0 or OpenAPI 3.x?

OpenAPI 3.x, always. 3.1 is preferred for new projects because it aligns with JSON Schema 2020-12; 3.0 is acceptable when your tooling lags behind. Swagger 2.0 is legacy.

YAML or JSON?

YAML is more readable for humans (comments, no quotes); JSON is friendlier to generators and CI. Most teams author in YAML and convert to JSON on demand. The two are formally equivalent for OpenAPI.

Can I run a mock server straight from the spec?

Yes — Prism (Stoplight) and Mockoon spin up an HTTP server that returns the examples and respects the schemas, perfect for frontend work before the backend is ready.

Does OpenAPI 3.1 really use JSON Schema?

Yes — 3.1 fully embeds JSON Schema Draft 2020-12, so any keyword from the JSON Schema vocabulary (oneOf, const, $defs) is legal in your schemas without translation. This was the main motivation for the 3.0 -> 3.1 jump.

What about webhooks and callbacks?

OpenAPI 3.1 introduced a top-level webhooks object to describe events your service emits; previously you would model them under callbacks inside operations. Both still work for backwards compatibility.