Visor OpenAPI

Understanding and Exploring OpenAPI Specifications

The OpenAPI Specification (OAS) is the industry standard for describing HTTP APIs in a machine-readable format. Originally known as Swagger, OpenAPI 3.x defines a structured document — written in JSON or YAML — that describes every endpoint, request parameter, response schema, authentication method, and server configuration of an API. This tool renders an OpenAPI 3.0 or 3.1 document into a navigable, human-readable view, allowing developers to explore API contracts without setting up a full documentation server or running code generation tooling.

OpenAPI 3.x Document Structure

An OpenAPI document is organized into a set of top-level objects that together form a complete API description. Understanding this structure is essential for reading and authoring specifications efficiently:

• openapi: The version string (e.g., "3.1.0") that tells parsers which rules to apply. Version 3.1 aligned OAS with JSON Schema 2020-12, while 3.0 uses a subset of JSON Schema Draft 07.
• info: Metadata about the API — title, version, description, contact information, license, and terms of service. This object is required and provides the human context for the specification.
• servers: An array of server objects defining base URLs where the API is hosted. Each server can include templated variables (e.g., {environment}) for staging/production switching.
• paths: The core of the specification. Each key is a URL path template (e.g., /users/{id}), and each value is a Path Item object containing operations for HTTP methods (GET, POST, PUT, DELETE, PATCH).
• components: A container for reusable definitions — schemas, response objects, parameters, request bodies, headers, security schemes, links, and callbacks. Components are referenced via $ref pointers throughout the document.
• security: Global security requirements applied to all operations unless overridden. References security schemes defined in components/securitySchemes.
• tags: Grouping metadata that organizes operations into logical categories for documentation rendering.

This hierarchical organization means a single OpenAPI file can describe APIs with hundreds of endpoints while keeping definitions DRY (Don't Repeat Yourself) through the $ref mechanism in the components section.

Paths, Operations, and Parameters

The paths object is where API behavior is defined. Each path can contain up to seven operation objects corresponding to HTTP methods: get, post, put, delete, patch, head, options, and trace. Each operation describes:

• Parameters: Inputs classified by location — path (URL template variables), query (query string), header (HTTP headers), or cookie. Each parameter has a name, schema, required flag, and description.
• Request Body: The payload for POST/PUT/PATCH operations, described with media type mappings (e.g., application/json) and a schema defining the expected structure.
• Responses: A map of HTTP status codes to response objects. Each response describes headers, content schemas per media type, and links to related operations.
• Security: Operation-level security overrides that can restrict or relax the global security requirements.
• Tags and Summary: Metadata used by documentation generators to group and describe operations in navigation panels.

When exploring a specification with this viewer, each operation is rendered with its full parameter list, request body schema, and response examples — giving developers a complete picture of how to call the endpoint without reading raw JSON or YAML.

Schemas and Components: Reusable Definitions

The components/schemas section contains data model definitions using JSON Schema vocabulary. In OpenAPI 3.1, schemas are fully compliant with JSON Schema 2020-12, supporting features like prefixItems, $dynamicRef, and the full set of annotation keywords. In OpenAPI 3.0, a restricted subset is used with OAS-specific extensions like nullable and discriminator.

Common schema patterns in OpenAPI documents include:

• Object schemas: Define properties, required fields, and additional property rules for request/response bodies.
• Composition: allOf for inheritance/extension, oneOf for polymorphism, anyOf for flexible unions. The discriminator keyword helps tools resolve polymorphic types.
• Array schemas: Define item types, minimum/maximum lengths, and uniqueness constraints for list responses and batch inputs.
• Enums and constants: Restrict values to a fixed set, commonly used for status fields, role types, and configuration flags.
• References: The $ref keyword points to a component path (e.g., "$ref": "#/components/schemas/User"), enabling schema reuse across multiple operations.

Beyond schemas, the components section also holds reusable parameters, responses, requestBodies, headers, securitySchemes, and callbacks — all referenceable via $ref from any location in the document.

Practical Workflows: Reading and Validating API Contracts

Developers interact with OpenAPI specifications in several common workflows where this viewer provides immediate value:

• API onboarding: When joining a project or integrating with a third-party service, loading the OpenAPI spec into this viewer reveals every available endpoint, its authentication requirements, expected inputs, and response shapes — faster than reading raw YAML files.
• Contract-first design review: Teams practicing API-first development write the spec before implementation. Viewing the rendered specification helps reviewers validate naming conventions, response structures, and error patterns without parsing YAML mentally.
• Specification completeness audit: Checking that all endpoints have descriptions, all parameters have examples, all responses define schemas, and security schemes are applied consistently. Missing elements are immediately visible in the rendered view.
• Version comparison preparation: Loading two versions of a spec helps identify added endpoints, deprecated operations, and schema changes between API releases.
• Client/SDK generation preview: Before running code generators like openapi-generator or oapi-codegen, reviewing the spec ensures the output will match expectations — particularly for polymorphic schemas and enum types that generators handle differently.

All processing happens entirely in the browser. Your API specification never leaves your machine — critical when working with internal APIs that contain proprietary endpoint structures or sensitive authentication configurations.

Code Examples

Minimal OpenAPI 3.1 specification

openapi: "3.1.0"
info:
  title: Bookstore API
  version: "1.0.0"
  description: A simple API for managing books
servers:
  - url: https://api.bookstore.example.com/v1
paths:
  /books:
    get:
      summary: List all books
      operationId: listBooks
      tags:
        - Books
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: A list of books
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Book"
    post:
      summary: Add a new book
      operationId: createBook
      tags:
        - Books
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BookInput"
      responses:
        "201":
          description: Book created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Book"
components:
  schemas:
    Book:
      type: object
      required:
        - id
        - title
        - author
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer
    BookInput:
      type: object
      required:
        - title
        - author
      properties:
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer

Standards & Specifications

• OpenAPI Specification 3.1.0 — The current OpenAPI specification version, fully aligned with JSON Schema 2020-12
• OpenAPI Specification 3.0.3 — The widely adopted 3.0 specification with OAS-specific JSON Schema subset
• JSON Schema 2020-12 — The schema language used by OpenAPI 3.1 for defining request and response data models