Success Icon

Contribute to this page

This documentation is Open source. If you have any feedback, suggestions, or want to contribute, check out our GitHub repo (opens in a new tab).

OpenAPI Icon

OpenAPI Hub

The all in one resource for understanding the OpenAPI Specification.

Powered by AI

API Framework Guides

FastAPI
FastAPI
Optimize the OpenAPI spec created from FastAPI projects
TypeSpec
TypeSpec
Optimize OpenAPI generation in TypeSpec projects
Zod
Zod
Generate OpenAPI schemas from your Zod models
Hono
Hono
Use one of the hottest 🔥 JS frameworks to build your spec
Pydantic
Pydantic
Generate OpenAPI schemas from your Pydantic models
Fastify
Fastify
OpenAPI for one of the most popular JS frameworks
Laravel
Laravel
Add OpenAPI to the most popular PHP framework
gRPC
gRPC
Use a reverse proxy server to build a REST interface on gRPC

OpenAPI Overview

openapi

The version of the OpenAPI Specification that the document conforms to, should be one of the supported versions (opens in a new tab).

Note: Speakeasy tooling currently only supports OpenAPI Specification versions 3.0.x and 3.1.x.

info

Contains information about the document including fields like title, version, and description that help to identify the purpose and owner of the document.

servers

Contains an optional list of servers the API is available on. If not provided, the default URL is assumed to be /, a path relative to where the OpenAPI document is hosted.

security

Contains an optional list of security requirements that apply to all operations in the API. If not provided, the default security requirements are assumed to be [], an empty array.

tags

Contains an optional list of tags that are generally used to group or categorize a set of Operations.

paths

Contains the paths and operations available within the API.

components

Contains an optional list of reusable schemas that can be referenced from other parts of the document. This improves the readability and maintainability of the document by allowing common schemas to be defined once and reused in multiple places.

openapi.yaml
openapi: 3.1.0

info:

  title: The Speakeasy Bar

  version: 1.0.0

servers:

  - url: https://speakeasy.bar

    description: The production server

security:

  - apiKey: []

tags:

  - name: drinks

    description: Operations related to drinks

paths:

  /drinks:

    get:

      tags:

        - drinks

      operationId: listDrinks

      summary: Get a list of drinks

      responses:

        "200":

          description: A list of drinks

          content:

            application/json:

              schema:

                type: array

                items:

                  $ref: "#/components/schemas/Drink"

components:

  schemas:

    Drink:

      type: object

      title: Drink

      properties:

        name:

          type: string

        price:

          type: number

  securitySchemes:

    apiKey:

      type: apiKey

      name: Authorization

      in: header

The OpenAPI Ecosystem

Understand the different specifications that make up the OpenAPI ecosystem

OpenAPI Overlays
OpenAPI Overlays

Describe customization to your OpenAPI

Read docs
OpenAPI 3.1
OpenAPI 3.1

Describe your API interface

Read docs
Arazzo Workflows
Arazzo Workflows

Describe your API workflows

Read docs

FAQ