> ## Documentation Index
> Fetch the complete documentation index at: https://backdrift.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI Specification

> The standard API definition format.

Backdrift generates a complete [OpenAPI 3.0](https://swagger.io/specification/) specification for your API. This is the industry-standard format for describing REST APIs.

## What's Included

The OpenAPI spec describes:

* **Endpoints** - All routes with methods (GET, POST, PUT, DELETE)
* **Parameters** - Path, query, and body parameters
* **Request Bodies** - JSON schemas for POST/PUT requests
* **Responses** - Success and error response schemas
* **Authentication** - Security schemes (Bearer token)
* **Servers** - Your deployed API URL

## Download Formats

| Format | Description                        |
| ------ | ---------------------------------- |
| JSON   | Machine-readable, best for tooling |
| YAML   | Human-readable, easier to edit     |

## Using the OpenAPI Spec

### Generate SDKs

```bash theme={null}
# Install OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript client
openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-fetch \
  -o ./sdk-ts

# Generate Python client
openapi-generator-cli generate \
  -i openapi.json \
  -g python \
  -o ./sdk-python
```

### Import into Postman

1. Open Postman
2. Click **Import**
3. Drag your `openapi.json` file
4. Postman creates a collection with all endpoints

### Generate Documentation

```bash theme={null}
# Using Redoc
npx @redocly/cli build-docs openapi.json

# Using Swagger UI
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/api/openapi.json \
  -v $(pwd):/api \
  swaggerapi/swagger-ui
```

### Validate API Contracts

```bash theme={null}
# Using Spectral
npm install -g @stoplight/spectral-cli
spectral lint openapi.json
```

## Sample OpenAPI Spec

```yaml theme={null}
openapi: 3.0.0
info:
  title: Task Manager API
  version: 1.0.0
  description: Auto-generated by Backdrift

servers:
  - url: https://abc123.execute-api.us-east-2.amazonaws.com
    description: Production

security:
  - bearerAuth: []

paths:
  /v1/tasks:
    get:
      summary: List tasks
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  next_cursor:
                    type: string

    post:
      summary: Create task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'

components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        priority:
          type: string
          enum: [low, medium, high]
        status:
          type: string
          enum: [pending, active, done]
        created_at:
          type: string
          format: date-time

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
```

## Interactive API Docs

Backdrift includes an interactive API documentation viewer (powered by Redoc):

1. Go to your project
2. Click **View API Docs**
3. Browse endpoints, try requests, and explore schemas

<Card title="Infrastructure Export" icon="server" href="/artifacts/infrastructure">
  Export the raw Infrastructure-as-Code.
</Card>