Swagger & Swagger UI {#config}#

🔥 Hot Tips

• You can change the Swagger endpoint by setting the environment variable SWAGGER_ROUTE eg. /my-swagger

Tina4 Python integrates Swagger for OpenAPI 3.0.3 compliant API documentation. The /swagger endpoint serves an interactive UI, and /swagger.json provides the JSON spec. Annotations via decorators add metadata to routes for enhanced docs.

Configuration {#configuration}#

Set environment variables for OpenAPI info:

• TINA4_SWAGGER_TITLE (default: "Tina4 Python API")
• TINA4_SWAGGER_DESCRIPTION (default: "Auto-generated API documentation")
• TINA4_SWAGGER_VERSION (default: "1.0.0")
• SWAGGER_CONTACT_TEAM (default: "Tina4 Team")
• SWAGGER_CONTACT_URL (default: "https://tina4.com")
• SWAGGER_CONTACT_EMAIL (default: "support@tina4.com")
• TINA4_HOST_NAME (default: "localhost:8000")
• BASE_URL (default: "")

Servers include current host and local dev. Security schemes: Bearer (JWT) and Basic for secure routes.

Import and Usage {#usage}#

Import decorators directly for cleaner usage without prefix:

from tina4_python import get  # Example router importfrom tina4_python import description, summary, secure, tags, example, example_response, params, describe

Apply above routes:

@get("/example")@description("Example route")async def example_route(request, response):    return response({"message": "Hello"})

Path params auto-detected; request bodies for POST/PUT/PATCH if examples given.

Decorators {#decorators}#

• @description(text: str): Operation description.
• @summary(text: str): Short summary.
• @secure(): Adds auth (Bearer JWT, Basic; 401 response).
• @tags(tags: list[str] | str): Grouping tags.
• @example(example_data: Any): Request example (POST/PUT/PATCH).
• @example_response(example_data: Any): 200 response example.
• @params(params_list: list[str] | dict[str, str]): Query params (e.g., ["page=1"] or {"limit": "10"}).
• @describe(...): Multi-annotation (args: description, summary, tags, params, example, example_response, secure: bool).

Routes without annotations skipped. Responses: 200 (with example), 400, 404; 401 if secure. Operation IDs auto-generated (e.g., get_users for GET /users). See swagger.py for generation details.

from tina4_python import postfrom tina4_python import description, summary, secure, tags, params, example, example_response​@post("/users")@description("Create a new user with provided details")@summary("User creation endpoint")@secure()@tags(["users", "auth"])@params(["referral_code", "plan=basic"])@example({"name": "Alice", "email": "alice@example.com", "age": 30})@example_response({"id": 1, "name": "Alice", "status": "active"})async def create_user(request, response):    # Implementation: Process request.body and create user    return response({"message": "User created"})

from tina4_python import postfrom tina4_python import describe​@post("/users")@describe(    description="Create a new user with provided details",    summary="User creation endpoint",    secure=True,    tags=["users", "auth"],    params=["referral_code", "plan=basic"],    example={"name": "Alice", "email": "alice@example.com", "age": 30},    example_response={"id": 1, "name": "Alice", "status": "active"})async def create_user(request, response):    # Implementation: Process request.body and create user    return response({"message": "User created"})​