Metadata-Version: 2.1
Name: tgext.apispec
Version: 0.1.0
Summary: OpenAPI specification generator for TurboGears2 controllers
Author-email: TurboGears Team <turbogears@groups.google.com>
License: MIT
Project-URL: Homepage, https://github.com/TurboGears/tgext.apispec
Project-URL: Repository, https://github.com/TurboGears/tgext.apispec
Project-URL: Issues, https://github.com/TurboGears/tgext.apispec/issues
Keywords: turbogears2.extension,TG2,OpenAPI,API,specification
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: TurboGears
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: TurboGears2>=2.5.1dev1
Requires-Dist: apispec>=3.0.0
Requires-Dist: marshmallow>=3.0.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: testing
Requires-Dist: pytest>=8; extra == "testing"
Requires-Dist: SQLAlchemy; extra == "testing"
Requires-Dist: WebTest; extra == "testing"
Provides-Extra: lint
Requires-Dist: ruff>=0.8; extra == "lint"

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:

.. code-block:: python

    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).to_dict()

    # The root controller is mounted at /. Child controllers are discovered
    # recursively.

Controller Example
------------------

.. code-block:: python

    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:

.. code-block:: python

    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.
