or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-commands.mdcore-classes.mdindex.mdopenapi-models.mdutilities.mdvalidation.md
tile.json

tessl/pypi-flask-openapi3

Generate REST API and OpenAPI documentation for your Flask project with automatic request/response validation using Pydantic models.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/flask-openapi3@4.2.x

To install, run

npx @tessl/cli install tessl/pypi-flask-openapi3@4.2.0

index.mddocs/

Flask-OpenAPI3

Flask-OpenAPI3 is a Flask extension that automatically generates REST API documentation and OpenAPI specifications. It provides request/response validation using Pydantic models, supports multiple OpenAPI UI templates, and follows the OpenAPI Specification 3.1.0 standard.

Package Information

  • Package Name: flask-openapi3
  • Language: Python
  • Installation: pip install flask-openapi3

Core Imports

from flask_openapi3 import OpenAPI

Working with blueprints and views:

from flask_openapi3 import APIBlueprint, APIView

Common model imports:

from flask_openapi3 import Info, Tag, Server
from flask_openapi3 import ValidationErrorModel, UnprocessableEntity
from flask_openapi3 import validate_request

All available model imports:

from flask_openapi3 import (
    APISpec, Components, Contact, Discriminator, Encoding, Example,
    ExternalDocumentation, FileStorage, Header, License, Link, MediaType,
    OAuthConfig, OAuthFlow, OAuthFlows, Operation, Parameter, ParameterInType,
    PathItem, RawModel, Reference, RequestBody, Response, Schema,
    SecurityScheme, ServerVariable, StyleValues, XML
)

Basic Usage

from flask_openapi3 import OpenAPI, Info
from pydantic import BaseModel

# Create OpenAPI app with metadata
info = Info(title="My API", version="1.0.0")
app = OpenAPI(__name__, info=info)

# Define request/response models
class UserQuery(BaseModel):
    name: str
    age: int = None

class UserResponse(BaseModel):
    id: int
    name: str
    age: int

# Create API endpoint with automatic validation
@app.post("/users", responses={200: UserResponse})
def create_user(query: UserQuery):
    """Create a new user"""
    # Request automatically validated against UserQuery
    return {"id": 1, "name": query.name, "age": query.age or 25}

if __name__ == "__main__":
    app.run(debug=True)

Architecture

Flask-OpenAPI3 extends Flask with automatic OpenAPI specification generation:

  • OpenAPI Class: Main Flask application with OpenAPI capabilities
  • APIBlueprint: Flask Blueprint with automatic documentation
  • APIView: Class-based views for organizing endpoints
  • Pydantic Models: Define request/response schemas and validation
  • Validation System: Automatic request validation and error handling
  • UI Templates: Multiple documentation interfaces (Swagger, Redoc, RapiDoc, etc.)

The library integrates seamlessly with Flask's routing and error handling while adding comprehensive API documentation and validation capabilities.

Capabilities

Core Application Classes

The main classes for building OpenAPI-enabled Flask applications, including the primary OpenAPI class, blueprint system, and class-based views.

class OpenAPI:
    def __init__(
        self,
        import_name: str,
        *,
        info: Optional[Info] = None,
        security_schemes: Optional[SecuritySchemesDict] = None,
        responses: Optional[ResponseDict] = None,
        servers: Optional[list[Server]] = None,
        external_docs: Optional[ExternalDocumentation] = None,
        operation_id_callback: Callable = get_operation_id_for_path,
        openapi_extensions: Optional[dict[str, Any]] = None,
        validation_error_status: Union[str, int] = 422,
        validation_error_model: Type[BaseModel] = ValidationErrorModel,
        validation_error_callback: Callable = make_validation_error_response,
        doc_ui: bool = True,
        doc_prefix: str = "/openapi",
        doc_url: str = "/openapi.json",
        **kwargs: Any
    ): ...

class APIBlueprint:
    def __init__(
        self,
        name: str,
        import_name: str,
        *,
        abp_tags: Optional[list[Tag]] = None,
        abp_security: Optional[list[dict[str, list[str]]]] = None,
        abp_responses: Optional[ResponseDict] = None,
        doc_ui: bool = True,
        operation_id_callback: Callable = get_operation_id_for_path,
        **kwargs: Any
    ): ...

class APIView:
    def __init__(
        self,
        url_prefix: Optional[str] = None,
        view_tags: Optional[list[Tag]] = None,
        view_security: Optional[list[dict[str, list[str]]]] = None,
        view_responses: Optional[ResponseDict] = None,
        doc_ui: bool = True,
        operation_id_callback: Callable = get_operation_id_for_path,
    ): ...

Core Application Classes

OpenAPI Models

Complete set of Pydantic models representing all OpenAPI 3.1.0 specification components, including API metadata, operation definitions, parameter specifications, and schema objects.

class Info(BaseModel):
    title: str
    version: str
    description: Optional[str] = None
    termsOfService: Optional[str] = None
    contact: Optional[Contact] = None
    license: Optional[License] = None

class Tag(BaseModel):
    name: str
    description: Optional[str] = None
    externalDocs: Optional[ExternalDocumentation] = None

class Server(BaseModel):
    url: str
    description: Optional[str] = None
    variables: Optional[dict[str, ServerVariable]] = None

class Parameter(BaseModel):
    name: str
    in_: ParameterInType = Field(..., alias="in")
    description: Optional[str] = None
    required: bool = False
    deprecated: bool = False
    allowEmptyValue: bool = False
    style: Optional[StyleValues] = None
    explode: Optional[bool] = None
    allowReserved: bool = False
    schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
    example: Optional[Any] = None
    examples: Optional[dict[str, Union[Example, Reference]]] = None

OpenAPI Models

Request Validation

Automatic request validation using Pydantic models for different parameter types including path, query, header, cookie, form data, and request body validation.

def validate_request():
    """
    Decorator for automatic request validation against Pydantic models.
    
    Applied automatically when using typed parameters in route handlers.
    Validates path, query, header, cookie, form, and body parameters.
    """

# Internal validation functions
def _validate_request(
    path: Optional[Type[BaseModel]] = None,
    query: Optional[Type[BaseModel]] = None,
    header: Optional[Type[BaseModel]] = None,
    cookie: Optional[Type[BaseModel]] = None,
    form: Optional[Type[BaseModel]] = None,
    body: Optional[Type[BaseModel]] = None,
    raw: Optional[Type[RawModel]] = None
) -> Callable: ...

Request Validation

Utility Functions

Helper functions for OpenAPI specification generation, parameter parsing, schema extraction, and operation management.

def get_operation(
    func: Callable, 
    *,
    summary: Optional[str] = None,
    description: Optional[str] = None,
    openapi_extensions: Optional[dict[str, Any]] = None,
) -> Operation: ...

def get_operation_id_for_path(
    *, 
    bp_name: str = "", 
    name: str = "", 
    path: str = "", 
    method: str = ""
) -> str: ...

def get_model_schema(
    model: Type[BaseModel], 
    mode: JsonSchemaMode = "validation"
) -> dict: ...

def parse_parameters(
    path: Optional[Type[BaseModel]] = None,
    query: Optional[Type[BaseModel]] = None,
    header: Optional[Type[BaseModel]] = None,
    cookie: Optional[Type[BaseModel]] = None,
    form: Optional[Type[BaseModel]] = None,
    body: Optional[Type[BaseModel]] = None,
    raw: Optional[Type[RawModel]] = None
) -> ParametersTuple: ...

Utility Functions

CLI Commands

Command-line interface for exporting OpenAPI specifications in JSON or YAML format.

@click.command(name="openapi")
@click.option("--output", "-o", type=click.Path(), help="The output file path.")
@click.option("--format", "-f", "_format", type=click.Choice(["json", "yaml"]), help="The output file format.")
@click.option("--indent", "-i", type=int, help="The indentation for JSON dumps.")
@with_appcontext
def openapi_command(output, _format, indent):
    """Export the OpenAPI Specification to console or a file"""

CLI Commands

Types

Core Type Aliases

ResponseDict = dict[Union[str, int, HTTPStatus], Union[Type[BaseModel], dict[Any, Any], None]]
SecuritySchemesDict = dict[str, Union[SecurityScheme, dict[str, Any]]]
ParametersTuple = tuple[
    Optional[Type[BaseModel]],  # path
    Optional[Type[BaseModel]],  # query
    Optional[Type[BaseModel]],  # header
    Optional[Type[BaseModel]],  # cookie
    Optional[Type[BaseModel]],  # form
    Optional[Type[BaseModel]],  # body
    Optional[Type[RawModel]]    # raw
]

Enums

class ParameterInType(str, Enum):
    query = "query"
    header = "header"
    path = "path"
    cookie = "cookie"

class HTTPMethod(str, Enum):
    GET = "GET"
    POST = "POST"
    PUT = "PUT"
    DELETE = "DELETE"
    PATCH = "PATCH"
    HEAD = "HEAD"
    OPTIONS = "OPTIONS"
    TRACE = "TRACE"
    CONNECT = "CONNECT"

class StyleValues(str, Enum):
    matrix = "matrix"
    label = "label"
    form = "form"
    simple = "simple"
    spaceDelimited = "spaceDelimited"
    pipeDelimited = "pipeDelimited"
    deepObject = "deepObject"

Constants

HTTP_STATUS: dict[str, str]  # HTTP status code to phrase mapping
OPENAPI3_REF_PREFIX: str = "#/components/schemas"
OPENAPI3_REF_TEMPLATE: str = "#/components/schemas/{model}"