OpenAPI & Swagger UI

openviper.openapi.schema

generate_openapi_schema(routes, title, version, description='') → dict

Generate an OpenAPI 3.1.0 schema dict from a list of Route objects.

• Path parameters (e.g. {id:int}) are included as parameters.

• Return type annotations that are Pydantic models are reflected into responses["200"]["content"].

• When a serializer_class is set on a class-based view, it is used to produce the requestBody schema.

• Python built-in types are mapped to JSON Schema types automatically.

reset_openapi_cache() → None

Clear the generated schema cache. Useful after dynamic route registration in tests.

openviper.openapi.ui

get_swagger_html(title, openapi_url) → str

Generate the Swagger UI HTML page that loads the schema from openapi_url.

get_redoc_html(title, openapi_url) → str

Generate the ReDoc HTML page.

Automatic Schema (Zero Configuration)

from openviper import OpenViper

app = OpenViper(
    title="Blog API",
    version="1.0.0",
)
# Schema available at /open-api/schema.json
# Swagger UI at /open-api/docs
# ReDoc at /open-api/redoc

Richer Schema via Pydantic Serializers

Attach a serializer_class to a class-based view to give Swagger UI an input form for the request body:

from openviper.http.views import View
from openviper.serializers import Serializer
from openviper.http.response import JSONResponse

class CreatePostSerializer(Serializer):
    title: str
    body: str
    tags: list[str] = []

class PostCreateView(View):
    serializer_class = CreatePostSerializer

    async def post(self, request) -> JSONResponse:
        data = CreatePostSerializer.validate(await request.json())
        post = await Post.objects.create(**data.model_dump())
        return JSONResponse(post._to_dict(), status_code=201)

PostCreateView.register(router, "/posts")

Return Type Annotation for Response Schema

from pydantic import BaseModel

class PostOut(BaseModel):
    id: int
    title: str
    body: str

@router.get("/posts/{post_id:int}")
async def get_post(request, post_id: int) -> PostOut:
    post = await Post.objects.get(id=post_id)
    return JSONResponse(post._to_dict())

The PostOut model is reflected into the OpenAPI responses section for this endpoint.

Accessing the Raw Schema

from openviper.openapi.schema import generate_openapi_schema
from openviper.routing.router import Router
import json

router = Router()
# ... register routes ...

schema = generate_openapi_schema(
    routes=router.routes,
    title="My API",
    version="2.0.0",
)
print(json.dumps(schema, indent=2))

Disable OpenAPI

Set OPENAPI_EXCLUDE = "__ALL__" to prevent the docs and schema endpoints from being registered. This is recommended for production deployments where you do not want to expose API documentation.

# settings.py

OPENAPI_EXCLUDE = "__ALL__"

After applying this setting, any request to /open-api/openapi.json, /open-api/docs, or /open-api/redoc will receive a 404 response.

Exclude Routes by Prefix

Pass a list of route-path prefixes (without the leading /) to remove matching paths from the generated schema. The docs endpoint itself remains accessible; only the schema content is filtered.

# Remove all /admin/* routes from the schema
OPENAPI_EXCLUDE = ["admin"]

# Remove /admin/* and /blogs/* routes
OPENAPI_EXCLUDE = ["admin", "blogs"]

# Remove /admin/*, /blogs/*, and /internal/* routes
OPENAPI_EXCLUDE = ["admin", "blogs", "internal"]

Prefix Matching Rules

• Matching is case-insensitive: "Admin" and "admin" produce the same result.

• Leading slashes in a prefix are normalised: "/admin" is treated identically to "admin".

• Only complete path segments are matched. A prefix of "blogs" will exclude /blogs and /blogs/posts but not /blogsearch or /blog.

Security Benefits

Using OPENAPI_EXCLUDE reduces the attack surface of your API:

• Hide internal admin endpoints from the public schema.

• Prevent automated scanners from discovering route structures.

• Disable the schema entirely in production to avoid information leakage.

API Reference — Exclusion Helpers

OPENAPI_EXCLUDE

Type: str | list[str] Default: []

Controls OpenAPI access and route exclusion.

Prefix matching rules:

• Case-insensitive: "Admin" and "admin" are equivalent.

• Leading slashes normalised: "/admin" and "admin" are identical.

• Whole-segment matching: "blogs" excludes /blogs and /blogs/posts but not /blogsearch or /blog.

All OpenAPI Settings

Configuration Examples

Disable OpenAPI entirely in production:

# settings.py
OPENAPI_EXCLUDE = "__ALL__"

Remove admin routes from the public schema:

OPENAPI_EXCLUDE = ["admin"]

Remove multiple path prefixes:

OPENAPI_EXCLUDE = ["admin", "blogs", "internal", "health"]

Security Considerations

• Disable the schema entirely (OPENAPI_EXCLUDE = "__ALL__") in production to prevent automated scanners from discovering your API surface.

• Use prefix exclusion to hide /admin and other sensitive sub-trees from publicly served documentation.

• Schema exposure is listed as a risk in OWASP API Security Top 10 (API7: Security Misconfiguration). OPENAPI_EXCLUDE directly mitigates this risk.