Ctrlk
Creator
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Swagger (OpenAPI)

Swagger/OpenAPI is a specification standard for describing, documenting, and generating client code for RESTful APIs.

Swagger is a set of tools for designing, building, documenting, and consuming RESTful APIs. The core of Swagger is the OpenAPI Specification (OAS), a language-agnostic, machine-readable format for describing HTTP APIs. Originally called the Swagger Specification, it was renamed to the OpenAPI Specification in 2016 when it was donated to the OpenAPI Initiative under the Linux Foundation. The terms "Swagger" and "OpenAPI" are often used interchangeably, though strictly speaking, Swagger now refers to the tooling while OpenAPI refers to the specification itself.

The OpenAPI Specification

An OpenAPI document is a JSON or YAML file that describes an API's endpoints, request and response formats, authentication methods, and other metadata. A typical specification includes:

  • Paths: Each API endpoint with its supported HTTP methods (GET, POST, PUT, DELETE, etc.).

  • Parameters: Query parameters, path parameters, headers, and cookies that the endpoint accepts.

  • Request bodies: The expected structure and content type of request payloads.

  • Responses: The structure of response payloads for each status code.

  • Security schemes: Authentication and authorization mechanisms such as API keys, OAuth 2.0, and JWT bearer tokens.

  • Components/schemas: Reusable data models that define the shape of objects used across the API.

Swagger tooling

The Swagger ecosystem includes several widely used tools:

  • Swagger Editor: A browser-based editor for writing and validating OpenAPI definitions.

  • Swagger UI: A tool that renders an OpenAPI document as interactive, browsable API documentation where developers can make live test requests.

  • Swagger Codegen / OpenAPI Generator: Code generation tools that produce client SDKs, server stubs, and API documentation from an OpenAPI file.

OpenAPI and API gateways

API gateways and OpenAPI specifications work well together. Many gateways can import an OpenAPI document to automatically configure routing rules, input validation, and documentation endpoints. This reduces manual configuration and ensures that the gateway's behavior stays in sync with the API design.

Serverless API Gateway uses a declarative YAML configuration that defines paths, methods, upstream servers, and authorization rules. Teams that maintain an OpenAPI specification for their API can use it as the reference when writing the gateway's path configuration, ensuring consistency between the documented API contract and the gateway's routing behavior.

Related documentation

PreviousStress Testing

Last updated