tessl/pypi-flask-openapi3

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

—

Pending

Overview

Eval results

Files

OpenAPI Models

Name: tessl/pypi-flask-openapi3
Author: tessl

Complete set of Pydantic models representing all OpenAPI 3.1.0 specification components. These models define the structure of API metadata, operation definitions, parameter specifications, schema objects, and other OpenAPI components.

Capabilities

Core Specification Models

Main models that define the overall API specification structure.

class APISpec(BaseModel):
    """Root OpenAPI specification object"""
    openapi: str
    info: Info
    servers: Optional[list[Server]] = None
    paths: Paths
    components: Optional[Components] = None
    security: Optional[list[SecurityRequirement]] = None
    tags: Optional[list[Tag]] = None
    externalDocs: Optional[ExternalDocumentation] = None
    webhooks: Optional[dict[str, Union[PathItem, Reference]]] = None

class Components(BaseModel):
    """Reusable OpenAPI components"""
    schemas: Optional[dict[str, Union[Schema, Reference]]] = None
    responses: Optional[dict[str, Union[Response, Reference]]] = None
    parameters: Optional[dict[str, Union[Parameter, Reference]]] = None
    examples: Optional[dict[str, Union[Example, Reference]]] = None
    requestBodies: Optional[dict[str, Union[RequestBody, Reference]]] = None
    headers: Optional[dict[str, Union[Header, Reference]]] = None
    securitySchemes: Optional[dict[str, Union[SecurityScheme, Reference]]] = None
    links: Optional[dict[str, Union[Link, Reference]]] = None
    callbacks: Optional[dict[str, Union[Callback, Reference]]] = None
    pathItems: Optional[dict[str, Union[PathItem, Reference]]] = None

class Paths(BaseModel):
    """Available paths and operations"""
    # Dynamic paths are added as additional properties
    model_config = {"extra": "allow"}

API Metadata Models

Models for describing API information, contact details, licensing, and external documentation.

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

class Contact(BaseModel):
    """Contact information for API"""
    name: Optional[str] = None
    url: Optional[str] = None
    email: Optional[str] = None

class License(BaseModel):
    """License information for API"""
    name: str
    identifier: Optional[str] = None
    url: Optional[str] = None

class ExternalDocumentation(BaseModel):
    """External documentation references"""
    description: Optional[str] = None
    url: str

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

Server Configuration Models

Models for defining API server information and variables.

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

class ServerVariable(BaseModel):
    """Server variable definitions"""
    enum: Optional[list[str]] = None
    default: str
    description: Optional[str] = None

Operation and Path Models

Models for defining API operations, paths, and their metadata.

class Operation(BaseModel):
    """API operation specification"""
    tags: Optional[list[str]] = None
    summary: Optional[str] = None
    description: Optional[str] = None
    externalDocs: Optional[ExternalDocumentation] = None
    operationId: Optional[str] = None
    parameters: Optional[list[Union[Parameter, Reference]]] = None
    requestBody: Optional[Union[RequestBody, Reference]] = None
    responses: Optional[Responses] = None
    callbacks: Optional[dict[str, Union[Callback, Reference]]] = None
    deprecated: bool = False
    security: Optional[list[SecurityRequirement]] = None
    servers: Optional[list[Server]] = None

class PathItem(BaseModel):
    """Operations available on a single path"""
    ref: Optional[str] = Field(default=None, alias="$ref")
    summary: Optional[str] = None
    description: Optional[str] = None
    get: Optional[Operation] = None
    put: Optional[Operation] = None
    post: Optional[Operation] = None
    delete: Optional[Operation] = None
    options: Optional[Operation] = None
    head: Optional[Operation] = None
    patch: Optional[Operation] = None
    trace: Optional[Operation] = None
    servers: Optional[list[Server]] = None
    parameters: Optional[list[Union[Parameter, Reference]]] = None

Parameter Models

Models for defining API parameters in different locations (path, query, header, cookie).

class Parameter(BaseModel):
    """API parameter specification"""
    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
    content: Optional[dict[str, MediaType]] = None

class Header(BaseModel):
    """Header parameter specification"""
    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
    content: Optional[dict[str, MediaType]] = None

Request and Response Models

Models for defining request bodies and API responses.

class RequestBody(BaseModel):
    """Request body specification"""
    description: Optional[str] = None
    content: dict[str, MediaType]
    required: bool = False

class Response(BaseModel):
    """API response specification"""
    description: str
    headers: Optional[dict[str, Union[Header, Reference]]] = None
    content: Optional[dict[str, MediaType]] = None
    links: Optional[dict[str, Union[Link, Reference]]] = None

class Responses(BaseModel):
    """Collection of response specifications"""
    default: Optional[Union[Response, Reference]] = None
    # HTTP status codes are added as additional properties
    model_config = {"extra": "allow"}

Schema and Data Models

Models for defining data schemas, media types, and examples.

class Schema(BaseModel):
    """JSON Schema definition"""
    # Schema properties follow JSON Schema specification
    title: Optional[str] = None
    multipleOf: Optional[float] = None
    maximum: Optional[float] = None
    exclusiveMaximum: Optional[bool] = None
    minimum: Optional[float] = None
    exclusiveMinimum: Optional[bool] = None
    maxLength: Optional[int] = Field(default=None, ge=0)
    minLength: Optional[int] = Field(default=None, ge=0)
    pattern: Optional[str] = None
    maxItems: Optional[int] = Field(default=None, ge=0)
    minItems: Optional[int] = Field(default=None, ge=0)
    uniqueItems: Optional[bool] = None
    maxProperties: Optional[int] = Field(default=None, ge=0)
    minProperties: Optional[int] = Field(default=None, ge=0)
    required: Optional[list[str]] = None
    enum: Optional[list[Any]] = None
    type: Optional[str] = None
    allOf: Optional[list[Union["Schema", Reference]]] = None
    oneOf: Optional[list[Union["Schema", Reference]]] = None
    anyOf: Optional[list[Union["Schema", Reference]]] = None
    not_: Optional[Union["Schema", Reference]] = Field(default=None, alias="not")
    items: Optional[Union["Schema", Reference]] = None
    properties: Optional[dict[str, Union["Schema", Reference]]] = None
    additionalProperties: Optional[Union[bool, "Schema", Reference]] = None
    description: Optional[str] = None
    format: Optional[str] = None
    default: Optional[Any] = None
    nullable: Optional[bool] = None
    discriminator: Optional[Discriminator] = None
    readOnly: Optional[bool] = None
    writeOnly: Optional[bool] = None
    example: Optional[Any] = None
    externalDocs: Optional[ExternalDocumentation] = None
    deprecated: Optional[bool] = None
    xml: Optional[XML] = None

class MediaType(BaseModel):
    """Media type definitions"""
    schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
    example: Optional[Any] = None
    examples: Optional[dict[str, Union[Example, Reference]]] = None
    encoding: Optional[dict[str, Encoding]] = None

class Example(BaseModel):
    """Example values for schema"""
    summary: Optional[str] = None
    description: Optional[str] = None
    value: Optional[Any] = None
    externalValue: Optional[str] = None

class Discriminator(BaseModel):
    """Discriminator for polymorphism"""
    propertyName: str
    mapping: Optional[dict[str, str]] = None

class XML(BaseModel):
    """XML metadata for schemas"""
    name: Optional[str] = None
    namespace: Optional[str] = None
    prefix: Optional[str] = None
    attribute: Optional[bool] = None
    wrapped: Optional[bool] = None

class Encoding(BaseModel):
    """Encoding property for request body"""
    contentType: Optional[str] = None
    headers: Optional[dict[str, Union[Header, Reference]]] = None
    style: Optional[StyleValues] = None
    explode: Optional[bool] = None
    allowReserved: Optional[bool] = None

Security Models

Models for defining API security schemes and requirements.

class SecurityScheme(BaseModel):
    """Security scheme definition"""
    type: str
    description: Optional[str] = None
    name: Optional[str] = None
    in_: Optional[str] = Field(default=None, alias="in")
    scheme: Optional[str] = None
    bearerFormat: Optional[str] = None
    flows: Optional[OAuthFlows] = None
    openIdConnectUrl: Optional[str] = None

class SecurityRequirement(BaseModel):
    """Security requirements for operations"""
    # Security scheme names are added as additional properties
    model_config = {"extra": "allow"}

class OAuthFlows(BaseModel):
    """OAuth2 flows configuration"""
    implicit: Optional[OAuthFlow] = None
    password: Optional[OAuthFlow] = None
    clientCredentials: Optional[OAuthFlow] = None
    authorizationCode: Optional[OAuthFlow] = None

class OAuthFlow(BaseModel):
    """OAuth2 flow configuration"""
    authorizationUrl: Optional[str] = None
    tokenUrl: Optional[str] = None
    refreshUrl: Optional[str] = None
    scopes: dict[str, str]

class OAuthConfig(BaseModel):
    """OAuth2 UI configuration"""
    clientId: Optional[str] = None
    clientSecret: Optional[str] = None
    realm: Optional[str] = None
    appName: Optional[str] = None
    scopeSeparator: Optional[str] = None
    scopes: Optional[str] = None
    additionalQueryStringParams: Optional[dict[str, str]] = None
    useBasicAuthenticationWithAccessCodeGrant: Optional[bool] = False
    usePkceWithAuthorizationCodeGrant: Optional[bool] = False

Reference and Link Models

Models for referencing other components and defining operation relationships.

class Reference(BaseModel):
    """Reference to another schema component"""
    ref: str = Field(..., alias="$ref")

class Link(BaseModel):
    """Link relationships between operations"""
    operationRef: Optional[str] = None
    operationId: Optional[str] = None
    parameters: Optional[dict[str, Any]] = None
    requestBody: Optional[Any] = None
    description: Optional[str] = None
    server: Optional[Server] = None

class Callback(BaseModel):
    """Callback object for webhooks"""
    # Expression names are added as additional properties
    model_config = {"extra": "allow"}

Special Models

Models for file handling, validation errors, and raw data processing.

class FileStorage(BaseModel):
    """File upload handling"""
    # Inherits from werkzeug.datastructures.FileStorage functionality
    # for handling multipart file uploads

class RawModel(Request):
    """Raw request data handling"""
    mimetypes: list[str] = ["application/json"]

class ValidationErrorModel(BaseModel):
    """Validation error response format"""
    detail: list[dict[str, Any]]

class UnprocessableEntity(BaseModel):
    """422 error response format"""
    detail: list[dict[str, Any]]

Usage Examples

Basic API Info Setup:

from flask_openapi3 import Info, Contact, License, Tag, Server

info = Info(
    title="My API",
    version="1.0.0",
    description="A sample API",
    contact=Contact(name="Developer", email="dev@example.com"),
    license=License(name="MIT")
)

tags = [
    Tag(name="users", description="User operations"),
    Tag(name="posts", description="Post operations")
]

servers = [
    Server(url="https://api.example.com", description="Production server"),
    Server(url="https://staging.example.com", description="Staging server")
]

Response Model Definition:

from flask_openapi3 import Response as OpenAPIResponse
from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str

class ErrorResponse(BaseModel):
    error: str
    message: str

# Define responses for endpoint
responses = {
    200: User,
    400: ErrorResponse,
    404: {"description": "User not found"}
}

Install with Tessl CLI