# Swagger (OpenAPI)

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

* [Path Routing](/configuration/paths.md) - Define API paths and methods in the gateway configuration
* [Configuration Overview](/configuration/overview.md) - Declarative YAML configuration format
* [Variable Mapping](/configuration/variable-mapping.md) - Map request parameters between clients and backends


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.serverlessapigateway.com/glossary/s/swagger-openapi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.