OpenAPI Specification

The standard API definition format.

Backdrift generates a complete OpenAPI 3.0 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

# 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

# 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

# Using Spectral
npm install -g @stoplight/spectral-cli
spectral lint openapi.json

Sample OpenAPI Spec

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

Infrastructure Export

Export the raw Infrastructure-as-Code.