OpenAPI Quick Reference

Common Commands

# Generate OpenAPI spec
databridge generate

# View spec location
cat src/openapi.json

# Start server with Swagger UI
npm run dev

# Visit Swagger UI
open http://localhost:3000/docs

# Download spec
curl http://localhost:3000/openapi.json > api-spec.json

URL Endpoints

Configuration

Enable/Disable OpenAPI

In .databridge.json:

{
  "api": {
    "openapi": {
      "enabled": true  // Set to false to disable
    }
  }
}

Custom Swagger UI Path

{
  "api": {
    "openapi": {
      "ui": {
        "swaggerUI": {
          "enabled": true,
          "path": "/api-docs"  // Default is /docs
        }
      }
    }
  }
}

Multiple Servers

{
  "api": {
    "openapi": {
      "servers": [
        { "url": "http://localhost:3000", "description": "Local" },
        { "url": "https://staging.api.com", "description": "Staging" },
        { "url": "https://api.com", "description": "Production" }
      ]
    }
  }
}

Generated Files

src/
├── openapi.json          ← OpenAPI 3.0 specification
├── plugins/
│   ├── prisma.ts
│   └── swagger.ts        ← Swagger UI plugin
├── routes/
│   ├── user.ts
│   ├── product.ts
│   └── _generated.ts
└── index.ts

Swagger UI Features

Testing Endpoints

1. Expand endpoint (click on it)
2. Click “Try it out”
3. Fill in parameters
4. Click “Execute”
5. View response

Filtering

• Click filter icon (funnel)
• Type to search: user, POST, create, etc.

Copying Requests

• Click “Try it out”
• Fill parameters
• Copy the “curl” command
• Use in terminal or scripts

Import to Tools

Postman

Import → Link → http://localhost:3000/openapi.json

Insomnia

Import/Export → From URL → http://localhost:3000/openapi.json

VS Code REST Client

1. Install REST Client extension
2. Create api-tests.http:

   @baseUrl = http://localhost:3000
   
   ### Get all users
   GET {{baseUrl}}/user
   
   ### Create user
   POST {{baseUrl}}/user
   Content-Type: application/json
   
   {
     "name": "John Doe",
     "email": "john@example.com"
   }

Spec Structure

{
  "openapi": "3.0.0",
  "info": {
    "title": "DataBridge API",
    "version": "1.0.0"
  },
  "servers": [...],
  "paths": {
    "/user": {
      "get": { ... },
      "post": { ... }
    },
    "/user/{id}": {
      "get": { ... },
      "put": { ... },
      "delete": { ... }
    }
  },
  "components": {
    "schemas": {
      "User": { ... },
      "CreateUserDTO": { ... },
      "UpdateUserDTO": { ... }
    }
  }
}

Common Operations

List All (GET)

GET /user?page=1&limit=10

Query params:

• page - Page number (default: 1)
• limit - Items per page (max: 100)

Get By ID (GET)

GET /user/123

Create (POST)

POST /user
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

Update (PUT)

PUT /user/123
Content-Type: application/json

{
  "name": "Jane Doe"
}

Delete (DELETE)

DELETE /user/123

Response Codes

Schema Types

Next Steps

• Full Tutorial - Complete guide
• API Testing - Contract testing with Dredd
• SDK Generation - Multi-language clients

Need help? Check the full OpenAPI tutorial