API Tutorials & OpenAPI Ecosystem

Welcome to DataBridge’s OpenAPI-first development toolkit! This guide covers everything from interactive API documentation to multi-language SDK generation.

🎯 Quick Navigation

Getting Started (5 minutes)

1. OpenAPI & Swagger UI - Interactive API documentation
2. Quick Reference - Commands and configuration cheat sheet

SDK Generation (10 minutes)

3. Multi-Language SDK Generation - Generate Python, Go, C#, Java, and 50+ language SDKs

Testing & Validation (15 minutes)

4. API Testing with Dredd - Contract testing for API reliability
5. Mock Servers with Prism - Frontend development without backend

🚀 What You’ll Learn

1. OpenAPI Specification

DataBridge automatically generates OpenAPI 3.0 specifications from your Prisma schema:

databridge generate
# Creates: src/openapi.json

Benefits:

• ✅ Single source of truth for your API
• ✅ Auto-synced with database schema
• ✅ Industry standard (95% of enterprise APIs)
• ✅ Tooling ecosystem (50+ compatible tools)

2. Interactive Documentation

Access Swagger UI at http://localhost:3000/docs:

npm run dev:api
open http://localhost:3000/docs

Features:

• 🧪 Try endpoints directly in browser
• 📋 See all request/response schemas
• 🔍 Search and filter endpoints
• 📥 Download OpenAPI spec

Perfect for:

• Testing APIs during development
• Sharing API docs with frontend teams
• Onboarding new developers
• API exploratory testing

3. Multi-Language SDK Generation

Generate type-safe client SDKs in 50+ languages:

# Single language
databridge generate-sdk --lang python

# Multiple languages
databridge generate-sdk --lang python,go,csharp,java

# Custom output directory
databridge generate-sdk --lang typescript --output ./client-libs

Supported Languages:

• Backend: Python, Go, Java, C#, Rust, PHP, Ruby, Kotlin, Elixir
• Frontend: TypeScript, JavaScript, Dart (Flutter)
• Mobile: Swift (iOS), Kotlin (Android)
• Data Science: R, Python (with pandas support)
• 50+ more

Each SDK includes:

• ✅ Full type safety
• ✅ CRUD operations
• ✅ Request validation
• ✅ Error handling
• ✅ Documentation & examples

4. Contract Testing with Dredd

Validate your API matches its contract:

# Setup Dredd
./scripts/setup-dredd.sh

# Run contract tests
npm run test:dredd

What Dredd does:

• Reads your OpenAPI spec
• Makes real HTTP requests to your API
• Validates responses match specification
• Reports discrepancies

Use cases:

• CI/CD integration
• Catch breaking changes
• Ensure spec accuracy
• API regression testing

5. Mock Servers with Prism

Develop frontend without backend:

# Start mock server
./scripts/start-prism.sh

# Mock server running at http://localhost:3334

What Prism does:

• Serves fake data based on OpenAPI spec
• Validates requests
• Simulates error responses
• No database required!

Use cases:

• Frontend development before backend ready
• Parallel development (frontend + backend teams)
• Integration testing
• Demo environments

📖 Tutorial Progression

Path 1: Backend Developer

1. OpenAPI & Swagger UI (Start here)

   • Generate OpenAPI spec
   • Explore Swagger UI
   • Test endpoints interactively
   • Download spec for sharing

2. API Testing with Dredd

   • Setup contract testing
   • Write custom hooks
   • Integrate with CI/CD
   • Validate API behavior

3. Multi-Language SDK Generation

   • Generate client SDKs
   • Publish to package registries
   • Distribute to teams
   • Version management

Path 2: Frontend Developer

1. Mock Servers with Prism (Start here)

   • Start mock server
   • Integrate with React/Vue/Angular
   • Simulate errors and delays
   • Develop without backend

2. OpenAPI & Swagger UI

   • Explore API endpoints
   • See request/response schemas
   • Test API integration
   • Understand available operations

3. Multi-Language SDK Generation

   • Generate TypeScript SDK
   • Use type-safe client
   • Handle errors properly
   • Best practices

Path 3: Full-Stack Team Lead

1. Quick Reference (Overview)

   • Command cheat sheet
   • Configuration options
   • Workflow diagrams
   • Common patterns

2. API Testing with Dredd

   • Setup CI/CD pipeline
   • Automate contract tests
   • Prevent breaking changes
   • Quality gates

3. Multi-Language SDK Generation

   • Automate SDK publishing
   • Distribute to teams
   • Version coordination
   • SDK best practices

🛠️ Common Workflows

Workflow 1: New API Endpoint

# 1. Update Prisma schema
# Edit prisma/schema.prisma

# 2. Regenerate everything
databridge generate

# 3. Check Swagger UI
npm run dev:api
open http://localhost:3000/docs

# 4. Test with Dredd
npm run test:dredd

# 5. Generate updated SDKs
databridge generate-sdk --lang python,typescript

Time saved: ~2 hours per endpoint (no manual docs, no manual SDK updates)

Workflow 2: Frontend-Backend Parallel Development

Backend Team:

# 1. Define API in Prisma schema
# 2. Generate OpenAPI spec
databridge generate

# 3. Share openapi.json with frontend team
# 4. Continue implementing backend logic

Frontend Team (same time):

# 1. Receive openapi.json
# 2. Start Prism mock server
./scripts/start-prism.sh

# 3. Develop frontend against mocks
# (No need to wait for backend!)

# 4. Switch to real API when ready
# Update API_URL from localhost:3334 → localhost:3000

Time saved: 40-50% development time (parallel work)

Workflow 3: Microservices Communication

Service A needs to call Service B:

# In Service B
cd service-b
databridge generate  # Creates openapi.json

# In Service A
cd service-a
databridge generate-sdk \
  --lang go \
  --api-dir ../service-b/src \
  --output ./clients/service-b

# Now Service A has type-safe Service B client!

Time saved: ~4 hours per service integration (no manual client code)

Workflow 4: API Release Process

# 1. Update version in Prisma schema comments
# 2. Regenerate everything
databridge generate

# 3. Run contract tests
npm run test:dredd

# 4. Generate SDKs for all languages
databridge generate-sdk --lang python,go,java,csharp,typescript

# 5. Publish SDKs to registries
cd sdks/python && twine upload dist/*
cd sdks/typescript && npm publish

# 6. Tag release
git tag v1.2.0 && git push --tags

🎓 Learning Resources

External Documentation

• OpenAPI Specification - Official spec
• Swagger UI - Interactive documentation
• OpenAPI Generator - SDK generation tool
• Dredd - Contract testing
• Prism - Mock server

Video Tutorials (Coming Soon)

• OpenAPI basics (5 min)
• SDK generation walkthrough (10 min)
• Contract testing deep dive (15 min)
• Full workflow demo (20 min)

Example Projects

• TypeScript + React example
• Python microservices example
• Mobile app (Swift + Kotlin)

💡 Best Practices

1. Version Your OpenAPI Specs

Update version in Prisma schema:

/// @openapi.info.version 1.2.0
generator client {
  provider = "prisma-client-js"
}

2. Add Descriptions

Use JSDoc-style comments:

/// User account information
model User {
  id    Int    @id @default(autoincrement())
  /// User's email address (must be unique)
  email String @unique
  name  String?
}

These become OpenAPI descriptions!

3. Test Before Releasing

# Always run before releasing
npm run test:dredd
./scripts/validate-openapi.sh

4. Automate SDK Publishing

Use CI/CD to publish SDKs on every release:

# .github/workflows/release.yml
- name: Publish SDKs
  run: |
    databridge generate-sdk --lang python,go,typescript
    # ... publish commands

5. Keep SDKs In Sync

Pin SDK versions to API versions:

# API v1.2.0 → SDK v1.2.0

🐛 Troubleshooting

Issue: OpenAPI spec not updating

Solution:

# Clean and regenerate
rm src/openapi.json
databridge generate

Issue: Swagger UI not loading

Solution:

# Check server logs
npm run dev:api

# Verify plugin loaded
# Look for: "Swagger UI available at /docs"

Issue: SDK generation failed

Solution:

# Validate spec first
./scripts/validate-openapi.sh

# Check openapi-generator-cli
npx openapi-generator-cli version

# Try with verbose logging
openapi-generator-cli generate \
  -i src/openapi.json \
  -g python \
  -o sdks/python \
  --verbose

Issue: Dredd tests failing

Solution:

# Check server is running
curl http://localhost:3000/health

# Verify openapi.json is valid
./scripts/validate-openapi.sh

# Check dredd configuration
cat dredd.yml

🚀 Next Steps

Ready to dive in? Start with:

1. OpenAPI & Swagger UI Tutorial - 10 minute quickstart
2. Generate Your First SDK - 5 minute guide
3. Setup Contract Testing - Ensure API quality

Questions? Open an issue on GitHub

Contributing? See CONTRIBUTING.md

Happy building with DataBridge! 🚀