Tutorial: Generate API Documentation with Swagger 5.0, FastAPI 0.120, and Postman 11.1

pip install fastapi swagger-ui-py postman-sdk uvicorn requests

# main.py
# Imports: FastAPI core, Swagger UI integration, error handling, pydantic for models
from fastapi import FastAPI, HTTPException, Query, Path, status
from fastapi.responses import JSONResponse
from swagger_ui_py import SwaggerUI  # Swagger 5.0 UI integration for FastAPI
from pydantic import BaseModel, Field, validator
from typing import List, Optional
import uvicorn
import logging
from datetime import datetime

# Configure logging for error tracking
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger(__name__)

# Initialize FastAPI app with OpenAPI metadata (used by Swagger 5.0)
app = FastAPI(
    title="Inventory Management API",
    description="Production-grade inventory API with auto-generated Swagger 5.0 docs, built with FastAPI 0.120",
    version="1.0.0",
    openapi_version="3.1.0",  # OpenAPI 3.1 required for Swagger 5.0 compatibility
    contact={
        "name": "Engineering Team",
        "email": "api@company.com"
    }
)

# Initialize Swagger UI 5.0 with custom config
swagger_ui = SwaggerUI(
    app=app,
    openapi_url="/openapi.json",  # FastAPI auto-generates this
    swagger_ui_bundle_version="5.0.0",  # Pin to Swagger 5.0
    swagger_ui_standalone_preset_version="5.0.0",
    config={
        "displayOperationId": True,
        "filter": True,
        "tryItOutEnabled": True  # Allow in-browser testing via Swagger UI
    }
)

# Pydantic models for request/response validation (FastAPI auto-generates Swagger schemas from these)
class ItemBase(BaseModel):
    name: str = Field(..., min_length=1, max_length=100, description="Name of the inventory item")
    quantity: int = Field(..., ge=0, description="Current quantity in stock")
    category: Optional[str] = Field(None, description="Optional item category")

    @validator("name")
    def name_must_not_be_empty(cls, v):
        if not v.strip():
            raise ValueError("Item name cannot be empty or whitespace")
        return v

class ItemCreate(ItemBase):
    sku: str = Field(..., regex=r"^[A-Z0-9]{6,12}$", description="Unique SKU (6-12 uppercase alphanumeric chars)")

class ItemResponse(ItemBase):
    id: int = Field(..., description="Unique item ID")
    sku: str
    created_at: datetime = Field(...)
    updated_at: datetime = Field(...)

# In-memory "database" for demo (replace with real DB in production)
fake_db = {}
next_id = 1

# Error handling: Custom 404 for item not found
@app.exception_handler(HTTPException)
async def http_exception_handler(request, exc):
    logger.error(f"HTTP error: {exc.status_code} - {exc.detail}")
    return JSONResponse(
        status_code=exc.status_code,
        content={"error": exc.detail, "timestamp": datetime.utcnow().isoformat()}
    )

# Endpoints with Swagger annotations (FastAPI auto-adds to OpenAPI spec)
@app.get(
    "/items",
    response_model=List[ItemResponse],
    summary="List all inventory items",
    response_description="List of items matching query filters"
)
async def list_items(
    category: Optional[str] = Query(None, description="Filter by item category"),
    min_quantity: Optional[int] = Query(None, ge=0, description="Minimum quantity filter")
):
    """Retrieve all inventory items, optionally filtered by category or minimum quantity."""
    results = list(fake_db.values())
    if category:
        results = [item for item in results if item.category == category]
    if min_quantity is not None:
        results = [item for item in results if item.quantity >= min_quantity]
    logger.info(f"Listed {len(results)} items with filters: category={category}, min_quantity={min_quantity}")
    return results

@app.post(
    "/items",
    response_model=ItemResponse,
    status_code=status.HTTP_201_CREATED,
    summary="Create new inventory item"
)
async def create_item(item: ItemCreate):
    """Create a new inventory item with unique SKU."""
    global next_id
    if any(existing.sku == item.sku for existing in fake_db.values()):
        raise HTTPException(status_code=400, detail=f"SKU {item.sku} already exists")
    new_item = ItemResponse(
        id=next_id,
        sku=item.sku,
        name=item.name,
        quantity=item.quantity,
        category=item.category,
        created_at=datetime.utcnow(),
        updated_at=datetime.utcnow()
    )
    fake_db[next_id] = new_item
    next_id += 1
    logger.info(f"Created item with ID {new_item.id} and SKU {new_item.sku}")
    return new_item

@app.get(
    "/items/{item_id}",
    response_model=ItemResponse,
    summary="Get single inventory item by ID"
)
async def get_item(item_id: int = Path(..., ge=1, description="ID of item to retrieve")):
    """Retrieve a single inventory item by its unique ID."""
    if item_id not in fake_db:
        raise HTTPException(status_code=404, detail=f"Item with ID {item_id} not found")
    return fake_db[item_id]

@app.delete(
    "/items/{item_id}",
    status_code=status.HTTP_204_NO_CONTENT,
    summary="Delete inventory item by ID"
)
async def delete_item(item_id: int = Path(..., ge=1, description="ID of item to delete")):
    """Delete an inventory item by its unique ID."""
    if item_id not in fake_db:
        raise HTTPException(status_code=404, detail=f"Item with ID {item_id} not found")
    del fake_db[item_id]
    logger.info(f"Deleted item with ID {item_id}")
    return None

if __name__ == "__main__":
    # Run with uvicorn for production-like serving
    uvicorn.run(
        app="main:app",
        host="0.0.0.0",
        port=8000,
        reload=False,  # Disable reload in production
        log_level="info"
    )

# sync_postman.py
# Imports for OpenAPI parsing, Postman SDK, error handling, HTTP requests
import json
import os
import sys
import logging
from typing import Dict, Any
from postman_sdk import PostmanClient  # Postman 11.1 SDK
from postman_sdk.models import Collection, Request, Response, Auth
import requests
from requests.exceptions import RequestException

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger(__name__)

# Configuration (use environment variables for production)
OPENAPI_URL = os.getenv("OPENAPI_URL", "http://localhost:8000/openapi.json")
POSTMAN_API_KEY = os.getenv("POSTMAN_API_KEY", "")  # Get from Postman 11.1 > Settings > API Keys
POSTMAN_COLLECTION_NAME = os.getenv("POSTMAN_COLLECTION_NAME", "Inventory API v1")
SWAGGER_VERSION = "5.0"  # Pinned Swagger version for compatibility checks

def fetch_openapi_spec() -> Dict[str, Any]:
    """Retrieve OpenAPI 3.1 spec from FastAPI app, validate Swagger 5.0 compatibility."""
    try:
        response = requests.get(OPENAPI_URL, timeout=10)
        response.raise_for_status()
        spec = response.json()
        # Validate OpenAPI version and Swagger compatibility
        if spec.get("openapi") != "3.1.0":
            logger.warning(f"OpenAPI version {spec.get('openapi')} may not be fully compatible with Swagger {SWAGGER_VERSION}")
        logger.info(f"Fetched OpenAPI spec version {spec.get('openapi')} from {OPENAPI_URL}")
        return spec
    except RequestException as e:
        logger.error(f"Failed to fetch OpenAPI spec: {e}")
        sys.exit(1)
    except json.JSONDecodeError as e:
        logger.error(f"Invalid OpenAPI spec JSON: {e}")
        sys.exit(1)

def convert_openapi_to_postman(openapi_spec: Dict[str, Any]) -> Collection:
    """Convert OpenAPI 3.1 spec to Postman 11.1 collection with full request/response mapping."""
    collection = Collection(
        name=POSTMAN_COLLECTION_NAME,
        description=openapi_spec.get("info", {}).get("description", "Auto-generated from Swagger 5.0 spec"),
        schema="https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    )

    # Map OpenAPI paths to Postman requests
    for path, methods in openapi_spec.get("paths", {}).items():
        for method, operation in methods.items():
            # Skip non-HTTP methods (e.g., parameters, servers)
            if method not in ["get", "post", "put", "delete", "patch"]:
                continue
            # Build Postman request
            request = Request(
                name=operation.get("summary", f"{method.upper()} {path}"),
                method=method.upper(),
                url=f"{{{{base_url}}}}{path}",  # Use Postman variable for base URL
                description=operation.get("description", ""),
                header=[
                    {"key": "Content-Type", "value": "application/json"},
                    {"key": "Accept", "value": "application/json"}
                ]
            )
            # Add query parameters if present
            if "parameters" in operation:
                for param in operation["parameters"]:
                    if param.get("in") == "query":
                        request.url.param.add({
                            "key": param["name"],
                            "value": param.get("schema", {}).get("default", ""),
                            "description": param.get("description", "")
                        })
            # Add request body if present (for POST/PUT)
            if "requestBody" in operation:
                content = operation["requestBody"].get("content", {}).get("application/json", {})
                if "example" in content:
                    request.body.raw = json.dumps(content["example"], indent=2)
                    request.body.mode = "raw"
            # Add sample responses from OpenAPI spec
            for status_code, response_spec in operation.get("responses", {}).items():
                response = Response(
                    name=f"{status_code} {response_spec.get('description', '')}",
                    status_code=int(status_code),
                    body=json.dumps(response_spec.get("content", {}).get("application/json", {}).get("example", {}), indent=2)
                )
                request.responses.append(response)
            # Add to collection folder (group by path prefix)
            path_parts = [p for p in path.split("/") if p and not p.startswith("{")]
            folder_name = path_parts[0] if path_parts else "root"
            folder = next((f for f in collection.folders if f.name == folder_name), None)
            if not folder:
                folder = collection.add_folder(folder_name)
            folder.add_request(request)
            logger.info(f"Mapped {method.upper()} {path} to Postman request")

    logger.info(f"Converted OpenAPI spec to Postman collection with {len(collection.folders)} folders")
    return collection

def upload_to_postman(collection: Collection) -> str:
    """Upload Postman 11.1 collection via Postman API, update if exists."""
    if not POSTMAN_API_KEY:
        logger.error("POSTMAN_API_KEY environment variable not set")
        sys.exit(1)
    client = PostmanClient(api_key=POSTMAN_API_KEY)
    try:
        # Check if collection already exists
        existing = next(
            (c for c in client.collections.all() if c.name == POSTMAN_COLLECTION_NAME),
            None
        )
        if existing:
            logger.info(f"Updating existing Postman collection: {existing.id}")
            updated = client.collections.update(existing.id, collection)
            return updated.id
        else:
            logger.info("Creating new Postman collection")
            created = client.collections.create(collection)
            return created.id
    except Exception as e:
        logger.error(f"Failed to upload to Postman: {e}")
        sys.exit(1)

if __name__ == "__main__":
    logger.info("Starting Swagger 5.0 to Postman 11.1 sync")
    openapi_spec = fetch_openapi_spec()
    postman_collection = convert_openapi_to_postman(openapi_spec)
    collection_id = upload_to_postman(postman_collection)
    logger.info(f"Successfully synced collection to Postman: https://app.postman.com/collections/{collection_id}")

# .github/workflows/sync-docs.yml
# GitHub Actions workflow to auto-sync Swagger 5.0 docs to Postman 11.1 on push to main
name: Sync API Docs

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

env:
  PYTHON_VERSION: "3.11"
  FASTAPI_VERSION: "0.120.0"
  SWAGGER_UI_VERSION: "5.0.0"
  POSTMAN_SDK_VERSION: "11.1.0"

jobs:
  generate-and-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python ${{ env.PYTHON_VERSION }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          cache: "pip"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install fastapi==${{ env.FASTAPI_VERSION }} \
                      swagger-ui-py==${{ env.SWAGGER_UI_VERSION }} \
                      postman-sdk==${{ env.POSTMAN_SDK_VERSION }} \
                      uvicorn[standard] \
                      requests
          echo "Installed dependencies: FastAPI $FASTAPI_VERSION, Swagger UI $SWAGGER_UI_VERSION, Postman SDK $POSTMAN_SDK_VERSION"

      - name: Start FastAPI app to generate OpenAPI spec
        run: |
          nohup uvicorn main:app --host 0.0.0.0 --port 8000 &
          sleep 5  # Wait for app to start
          # Verify app is running
          curl -f http://localhost:8000/docs || (echo "FastAPI app failed to start" && exit 1)
          echo "FastAPI app running, OpenAPI spec available at http://localhost:8000/openapi.json"

      - name: Run sync script to update Postman collection
        env:
          POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
          OPENAPI_URL: "http://localhost:8000/openapi.json"
          POSTMAN_COLLECTION_NAME: "Inventory API v1"
        run: |
          python sync_postman.py
          echo "Postman collection synced successfully"

      - name: Validate Swagger 5.0 UI accessibility
        run: |
          # Check Swagger UI loads correctly
          curl -f http://localhost:8000/docs | grep -q "swagger-ui" || (echo "Swagger UI not accessible" && exit 1)
          echo "Swagger 5.0 UI validated"

      - name: Upload OpenAPI spec as artifact
        uses: actions/upload-artifact@v4
        with:
          name: openapi-spec
          path: openapi.json
          retention-days: 7

      - name: Notify on failure
        if: failure()
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          text: "API doc sync failed for ${{ github.repository }} @ ${{ github.sha }}"
          webhook_url: ${{ secrets.SLACK_WEBHOOK }}

# requirements.txt (pinned for Swagger 5.0 + FastAPI 0.120 + Postman 11.1)
fastapi==0.120.0
swagger-ui-py==5.0.0
postman-sdk==11.1.0
uvicorn[standard]==0.29.0
pydantic==2.7.0  # Pydantic v2 required for FastAPI 0.120
markupsafe==2.1.5  # Pinned for swagger-ui-py 5.0.0 compatibility
jinja2==3.1.4

// Postman test script for schema validation
pm.test("Request matches Swagger 5.0 OpenAPI spec", function() {
    const openapiSpec = pm.collectionVariables.get("openapi_spec");
    const currentRequest = pm.request;
    // Validate request URL matches OpenAPI path
    const path = currentRequest.url.getPath();
    const method = currentRequest.method.toLowerCase();
    if (!openapiSpec.paths[path] || !openapiSpec.paths[path][method]) {
        pm.expect.fail(`Path ${path} with method ${method} not found in OpenAPI spec`);
    }
    // Validate response status code is documented
    pm.response.to.have.status(Object.keys(openapiSpec.paths[path][method].responses));
});

# Add to main.py after initializing the FastAPI app
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:8000", "https://docs.yourcompany.com"],  # Swagger UI domains
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],  # Match your API's methods
    allow_headers=["Content-Type", "Authorization"],
)

fastapi-swagger-postman-docs/
├── main.py                  # FastAPI app with Swagger 5.0 integration
├── sync_postman.py          # Script to sync OpenAPI spec to Postman 11.1
├── requirements.txt         # Pinned dependencies
├── .github/
│   └── workflows/
│       └── sync-docs.yml    # CI/CD pipeline for auto-sync
├── tests/
│   ├── test_api.py          # FastAPI endpoint tests
│   └── test_postman_sync.py # Postman sync validation tests
├── README.md                # Tutorial summary and setup instructions
└── .env.example             # Example environment variables