tgext.apispec

OpenAPI specification generator for TurboGears2 controllers.

This extension automatically generates OpenAPI specifications from TurboGears controllers by introspecting @validate decorators and docstrings.

Installation

pip install tgext.apispec

Usage

Basic usage in your TurboGears application:

import tg
from tg import expose
from tg.controllers import TGController
from tgext.apispec.openapi import get_spec

class RootController(TGController):
    @expose("json")
    def openapi(self):
        # Each call builds the complete specification.
        return get_spec(self, prefix=tg.url('/api')).to_dict()

# ``prefix`` is caller-controlled; this example generates paths under
# ``/api``. Child controllers are discovered recursively.

Controller Example

from tg import expose, validate
from tg.controllers import RestController
from tg.validation import Convert, RequireValue

class MoviesController(RestController):
    @expose('json')
    @validate({
        'title': RequireValue(),
        'year': Convert(int, default=None),
    })
    def post(self, title, year=None):
        """Create a new movie.

        ---
        tags: [movies]
        responses:
          201:
            description: Movie created
          412:
            description: Validation error
        """
        # Your implementation
        ...

The extension will automatically:

• Extract parameter types from @validate decorators
• Parse docstrings for descriptions and metadata using a --- separator
• Generate proper OpenAPI schema for each endpoint

Features

• Automatic Parameter Extraction: Extracts parameter types from @validate decorators
• Docstring Support: Uses docstrings for descriptions, tags, and response definitions
• RestController Support: Properly handles RestController methods (get_all, get_one, post, put, delete)
• Type Conversion: Converts TG validators to OpenAPI types (int, float, bool, string, email, date, datetime)
• JSON Endpoints Only: Only generates spec for JSON-exposed endpoints

Docstring Format

Use a --- separator in your docstring to add OpenAPI metadata:

def my_action(self):
    """My action description.

    ---
    tags: [my_tag]
    responses:
      200:
        description: Success
      404:
        description: Not found
    """

Supported docstring metadata:

• tags: List of tags for the endpoint
• responses: Response definitions
• description: Endpoint description, automatically extracted from the first part of the docstring

Development

The package targets TurboGears 2.5.1, which is expected to come from the TurboGears development branch until that version is released.

python -m pip install "TurboGears2 @ git+https://github.com/TurboGears/tg2.git@development"
python -m pip install -e ".[testing,lint]"
python -m pytest
python -m ruff format --check .
python -m ruff check .

License

MIT License. See LICENSE for details.