Add OpenAPI/Swagger API Documentation

[Tim020]

Overview

Add OpenAPI/Swagger documentation to DigiScript's REST API, including an interactive Swagger UI page for exploring and testing endpoints.

Motivation

• Developer Experience: Interactive API documentation makes it easier for contributors to understand available endpoints
• Client Development: Auto-generated API specs can be used to generate client SDKs
• Testing: Swagger UI provides built-in API testing capabilities
• Maintenance: Auto-generated docs stay in sync with code changes

Research Summary

After researching available options for Python Tornado + Marshmallow stack, there are three viable approaches:

Option 1: apispec + apispec-webframeworks (Recommended)

Pros:

• Official Marshmallow integration - can auto-generate schemas from our existing SQLAlchemyAutoSchema classes
• OpenAPI 3.0 support
• Most flexible and well-maintained (actively developed by marshmallow-code org)
• Works with our existing Marshmallow schemas in schemas/schemas.py
• Tornado plugin available via apispec-webframeworks

Cons:

• Requires more manual setup for path registration
• Need to write code to generate and serve the spec file

Example Integration:

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec_webframeworks.tornado import TornadoPlugin

spec = APISpec(
    title="DigiScript API",
    version="1.0.0",
    openapi_version="3.0.0",
    plugins=[MarshmallowPlugin(), TornadoPlugin()],
)

# Auto-generates schema from existing Marshmallow schemas
spec.components.schema("Show", schema=ShowSchema)

References:

• apispec on GitHub
• apispec-webframeworks Tornado plugin
• apispec documentation

Option 2: tornado-swagger

Pros:

• Simple decorator-based approach
• Built-in Swagger UI at /api/doc
• Minimal code changes needed

Cons:

• Requires embedding YAML specs in docstrings
• Less integration with existing Marshmallow schemas
• May require duplicating schema definitions

Example:

@ApiRoute("/show/script", ApiVersion.V1)
class ScriptController(BaseAPIController):
    @requires_show
    def get(self):
        """
        ---
        tags:
          - Script
        summary: Get script page
        parameters:
          - name: page
            in: query
            required: true
            schema:
              type: integer
        responses:
          200:
            description: Script page retrieved
        """

References:

• tornado-swagger on GitHub
• tornado-swagger on PyPI
• Using Swagger with Tornado (Medium article)

Option 3: tornado-swirl

Pros:

• OpenAPI 3.0 native support
• Uses Google-style docstrings (more readable than YAML)
• Adapted for modern Tornado 5+ and Python 3

Cons:

• Less maintained than apispec
• Requires @restapi decorator for route registration (different from our @ApiRoute)
• May require refactoring our routing system

References:

• tornado-swirl on GitHub

Implementation Considerations

Integration with Existing Architecture

DigiScript uses:

• Custom routing: @ApiRoute decorator with automatic /api/v{version}/ prefix
• Existing Marshmallow schemas: Already defined in schemas/schemas.py using SQLAlchemyAutoSchema
• Auto-discovery: Controllers in controllers/api/ are auto-loaded via module_discovery.py

Recommended Approach

Option 1 (apispec) appears best because:

1. ✅ Reuses existing Marshmallow schemas (no duplication)
2. ✅ Mature, actively maintained project
3. ✅ OpenAPI 3.0 support
4. ✅ Can integrate with our custom @ApiRoute decorator

Implementation Steps

1. Add dependencies:

   pip install apispec apispec-webframeworks swagger-ui-py

2. Create spec generator (utils/api_spec.py):

   • Initialize APISpec with Marshmallow + Tornado plugins
   • Auto-register schemas from schemas/schemas.py
   • Create decorator or helper to register routes from @ApiRoute controllers

3. Add Swagger UI endpoint:

   • New controller at /api/docs serving Swagger UI
   • Spec JSON endpoint at /api/openapi.json

4. Document existing endpoints:

   • Add docstrings to controller methods
   • Use spec.path() to register routes with parameters/responses

5. Update documentation:

   • Add link to API docs in README
   • Document how to add specs for new endpoints

Acceptance Criteria

• OpenAPI 3.0 spec generated from existing Marshmallow schemas
• Interactive Swagger UI accessible at /api/docs
• OpenAPI spec JSON available at /api/openapi.json
• At least 5-10 key endpoints documented as examples
• Documentation in README on how to add API docs for new endpoints
• CI checks pass (linting, tests)

Additional References

• apispec Marshmallow OpenAPI integration
• swagger-ui-py documentation
• OpenAPI 3.0 Specification