Issue 22: OpenAPI Spec and Postman Collection

[laraibg786]

Goal

Use FastAPI's built-in OpenAPI generation to produce an OpenAPI 3.0 spec, and convert it to a Postman collection with environment variables for easy API testing.

Requirements

Functional

• Configure FastAPI with title "Permit License Platform", version "1.0.0", openapi_url="/openapi.json", docs_url="/docs".
• Export OpenAPI spec to docs/openapi.json.
• Create a Postman collection v2.1 (docs/postman-collection.json) covering all endpoints: /auth/*, /licenses/*, /licenses/activate, /licenses/heartbeat.
• Create a Postman environment file (docs/postman-environment.json) with pre-populated variables: base_url, vendor_id, session_token, license_key.
• Document JWT Bearer auth scheme for all protected endpoints.
• Include example requests and responses for each endpoint.

Technical

• Export Script: python -c "from app.main import app; import json; print(json.dumps(app.openapi()))" > docs/openapi.json.
• Postman Conversion: Python script to map OpenAPI paths to Postman items.

Acceptance Criteria

• GET /openapi.json returns a valid OpenAPI 3.0 spec.
• All endpoints are documented in the spec and Postman collection.
• Postman collection imports without errors.
• Bearer token auth is pre-configured in the collection.

Dependencies

• Blocked by: Issue 01: FastAPI scaffold #1 to Issue 20: Heartbeat Grace Period Enforcement #20 (all endpoints must exist).
• Blocks: Issue 30: Postman API Release Checklist #30 (Release Checklist).