Skip to content

Interactive API Documentation (Swagger UI)

Overview

MSN Weather Wrapper provides interactive API documentation powered by Swagger UI (generated by FastAPI). This allows you to explore, test, and understand the API directly from your browser.

Accessing Swagger UI

Local Development

When running the API locally: 

http://localhost:5000/apidocs

Container Deployment

The bundled Nginx config (infra/config/nginx.conf) only proxies /api/ to the backend, so Swagger UI is not reachable through port 8080 of the unified container. Use the development API on port 5000, or add proxy rules for /apidocs and /apispec.json.

Production

Swagger UI is served by the FastAPI process itself; it is available wherever that process (or a proxy rule for it) is exposed: 

https://your-domain.com/apidocs

Features

📖 Complete Documentation

  • All endpoints documented with descriptions
  • Request parameter specifications (query, body, headers)
  • Response schemas with examples
  • Error response documentation

🧪 Interactive Testing

  • Try it out: Execute API calls directly from the browser
  • Real-time responses: See actual API responses
  • Parameter validation: Test with different inputs
  • Authentication support: Session-based auth for recent searches

🏷️ Organized by Category

  • Health: Health checks, liveness, readiness probes
  • Weather: Weather data retrieval and recent search history endpoints

🔍 Schema Validation

  • OpenAPI 3 specification generated by FastAPI
  • Type-safe request/response schemas
  • Automatic validation feedback

OpenAPI Specification

The raw OpenAPI specification is available at: 

http://localhost:5000/apispec.json

This can be imported into: - Postman - Insomnia - API testing tools - Code generators

Available Endpoints

Health Endpoints

Endpoint Method Description
/api/v1/health GET Basic health check
/api/v1/health/live GET Kubernetes liveness probe
/api/v1/health/ready GET Kubernetes readiness probe

Weather Endpoints

Endpoint Method Description
/api/v1/weather GET Get weather by city (query params)
/api/v1/weather POST Get weather by city (JSON body)
/api/v1/weather/coordinates GET Get weather by latitude/longitude

Search History Endpoints

Endpoint Method Description
/api/v1/recent-searches GET Get recent search history
/api/v1/recent-searches DELETE Clear search history

Using Swagger UI

1. Explore Endpoints

Click on any endpoint to view: - Description and purpose - Required/optional parameters - Request/response examples - Authentication requirements

2. Test an Endpoint

  1. Click "Try it out" button
  2. Fill in required parameters
  3. Click "Execute"
  4. View the response below

3. Example: Test Weather API

1. Navigate to: http://localhost:5000/apidocs
2. Find "GET /api/v1/weather" under "weather" tag
3. Click "Try it out"
4. Enter:
   - city: Seattle
   - country: USA
5. Click "Execute"
6. See the live weather response!

Authentication

For endpoints requiring session authentication (recent searches): 1. Make a weather request first to establish a session 2. The session cookie will be automatically included 3. Recent searches endpoints will now work

Rate Limiting

Rate limits are enforced: - Per IP: 30 requests/minute (all endpoints) - Global: 200 requests/hour

Exceeding limits returns HTTP 429 (Too Many Requests).

Configuration

Swagger UI configuration in backend/api/main.py: 

app = FastAPI(
    docs_url="/apidocs",
    openapi_url="/apispec.json",
    redoc_url=None,
    # ... other settings
)

The generated OpenAPI document includes: - API metadata (title, description, version) - Contact information - Tag descriptions - License information

Benefits

For Developers

  • ✅ No need to read lengthy documentation
  • ✅ Test APIs without writing code
  • ✅ Understand request/response structure instantly
  • ✅ Export OpenAPI spec for code generation

For Testing

  • ✅ Manual integration testing
  • ✅ Validate API behavior
  • ✅ Debug request/response issues
  • ✅ Share API capabilities with team

For Documentation

  • ✅ Always up-to-date with code
  • ✅ Interactive examples
  • ✅ Self-service API exploration
  • ✅ Reduces support questions

Troubleshooting

Swagger UI Not Loading

# Check if the API is running
curl http://localhost:5000/api/v1/health

# Verify Swagger route
curl http://localhost:5000/apispec.json

404 Not Found

  • Verify the API is running on the expected port
  • Check for proxy configuration issues (the container's Nginx does not forward /apidocs)

Missing Endpoints

  • Endpoints must be registered on a router included in backend/api/main.py
  • Check server logs for startup errors

Quick Start: 

# Start the API
uvicorn backend.api.main:app --reload --port 5000

# Open your browser to:
http://localhost:5000/apidocs

Enjoy exploring the API! 🚀