OpenAPI & Swagger UI Tutorial

Overview

DataBridge automatically generates OpenAPI 3.0 specifications from your Prisma schema and includes Swagger UI for interactive API documentation and testing.

What You Get

When you run databridge generate, you automatically get:

• ✅ OpenAPI 3.0 Spec (openapi.json) - Industry-standard API documentation
• ✅ Swagger UI at /docs - Interactive API explorer
• ✅ Spec Endpoint at /openapi.json - Downloadable specification
• ✅ Try-it-out functionality - Test APIs directly in your browser
• ✅ Request/Response schemas - Auto-generated from Prisma models
• ✅ CRUD endpoints - Full REST API documentation

Quick Start

1. Generate Your API

databridge generate

This creates:

• src/openapi.json - Your complete API specification
• src/plugins/swagger.ts - Swagger UI plugin
• All API routes with OpenAPI-compliant structure

2. Start Your Server

npm run dev

3. Visit Swagger UI

Open your browser to:

http://localhost:3000/docs

You’ll see an interactive API documentation page with all your endpoints!

Using Swagger UI

Exploring Endpoints

Swagger UI organizes endpoints by model (e.g., User, Product, Order):

▼ User
  GET    /user      - List all users
  POST   /user      - Create a new user
  GET    /user/{id} - Get user by ID
  PUT    /user/{id} - Update user
  DELETE /user/{id} - Delete user

Testing Endpoints

1. Expand an endpoint (click on it)
2. Click “Try it out”
3. Fill in parameters (path params, query params, request body)
4. Click “Execute”
5. View results - See response body, status code, headers

Example: Create a User

1. Find POST /user endpoint
2. Click “Try it out”
3. Edit the request body:

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

4. Click “Execute”
5. See the created user in the response!

Example: List Users with Pagination

1. Find GET /user endpoint
2. Click “Try it out”
3. Set query parameters:
   • page: 1
   • limit: 10
4. Click “Execute”
5. See paginated results!

OpenAPI Spec Features

DataBridge generates a complete OpenAPI 3.0 specification with:

Request/Response Schemas

Every endpoint has typed schemas:

components:
  schemas:
    User:
      type: object
      required:
        - name
        - email
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        email:
          type: string
        createdAt:
          type: string
          format: date-time

DTOs (Data Transfer Objects)

• CreateUserDTO - For POST requests (no id, createdAt, updatedAt)
• UpdateUserDTO - For PUT requests (all fields optional)
• User - Complete model with all fields

Validation Rules

Schemas include validation from your Prisma schema:

name:
  type: string
  minLength: 1
  maxLength: 255
age:
  type: integer
  minimum: 0
  maximum: 120

Error Responses

All endpoints document error responses:

• 400 - Bad Request (validation errors)
• 404 - Not Found (resource doesn’t exist)
• 500 - Internal Server Error

Exporting the Spec

Download JSON

Visit: http://localhost:3000/openapi.json

Or from Swagger UI:

1. Click the /openapi.json link at the top
2. Right-click → “Save As…”

Import to Other Tools

The OpenAPI spec works with:

• Postman - Import → OpenAPI 3.0
• Insomnia - Import → From URL or File
• Bruno - Import OpenAPI specification
• VS Code REST Client - Generate requests from spec
• API Gateway - AWS API Gateway, Kong, Apigee

Integration with Testing Tools

Postman Collection

Import your OpenAPI spec into Postman:

1. Open Postman
2. Click “Import”
3. Select “Link” tab
4. Enter: http://localhost:3000/openapi.json
5. Click **“Continue”

Now you have a full Postman collection with all endpoints!

Insomnia Collection

1. Open Insomnia
2. Click “Import/Export” → “Import Data”
3. Select “From URL”
4. Enter: http://localhost:3000/openapi.json
5. Click **“Fetch and Import”

Thunder Client (VS Code)

1. Install Thunder Client extension
2. Click “Import”
3. Select “OpenAPI”
4. Choose your openapi.json file

Advanced Features

Custom Servers

Update .databridge.json to add server URLs:

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

Now Swagger UI shows a server dropdown!

Adding Descriptions

Add documentation to your Prisma models:

/// User account with authentication details
model User {
  id    Int     @id @default(autoincrement())
  
  /// User's full name
  name  String
  
  /// Unique email address for login
  email String  @unique
  
  createdAt DateTime @default(now())
}

These appear in Swagger UI and the OpenAPI spec!

Filtering Endpoints

Swagger UI includes built-in filtering:

1. Click the “Filter” icon (funnel)
2. Type to filter endpoints:
   • user - Shows only User endpoints
   • POST - Shows only POST endpoints
   • create - Shows endpoints with “create” in name

Best Practices

1. Keep Swagger UI Open While Developing

Visit /docs in a separate browser tab. As you make changes and restart the server, refresh to see updated documentation.

2. Test in Swagger UI First

Before writing frontend code, test your API in Swagger UI. It’s faster than:

• Writing curl commands
• Setting up Postman collections manually
• Debugging frontend fetch/axios calls

3. Share with Team

Send team members the Swagger UI link:

http://localhost:3000/docs  (local dev)
https://staging.api.example.com/docs  (staging)

They can explore and test the API without installing anything!

4. Use for Frontend Development

Frontend developers can:

1. Visit /docs to see all available endpoints
2. Click “Try it out” to see example requests/responses
3. Copy the request format for their fetch/axios calls
4. Know exactly what data shape to expect

5. Export for API Gateways

If deploying to AWS API Gateway, Kong, or Apigee:

1. Download openapi.json
2. Import directly into your API gateway
3. Gateway automatically configures routes, validation, docs

Troubleshooting

Swagger UI Not Loading

Check server logs:

npm run dev

Look for:

📚 Swagger UI available at /docs
📄 OpenAPI spec available at /openapi.json

Check file exists:

ls src/openapi.json

If missing, run databridge generate again.

”Failed to Load API Definition”

Validate your spec:

1. Visit: https://editor.swagger.io
2. Paste contents of openapi.json
3. Fix any validation errors

Common issues:

• Missing required fields in schemas
• Invalid type mappings
• Circular references in models

Endpoints Not Showing

Regenerate after schema changes:

# After modifying schema.prisma
prisma db push
databridge generate  # Regenerates OpenAPI spec
npm run dev

Next Steps

• API Testing with Dredd - Contract testing
• Mock Servers with Prism - Frontend parallel development
• Multi-Language SDKs - Generate Python, Go, C# clients
• Postman Integration - Advanced testing workflows

Resources

• OpenAPI Specification 3.0
• Swagger UI Documentation
• Swagger Editor - Validate your spec
• OpenAPI Tools - Discover 100+ OpenAPI tools

Have questions? Open an issue on GitHub