or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

components.mdcore-spec.mdindex.mdmarshmallow.mdplugin-system.mdutils.md
tile.json

tessl/pypi-apispec

A pluggable API specification generator for OpenAPI/Swagger specifications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/apispec@6.8.x

To install, run

npx @tessl/cli install tessl/pypi-apispec@6.8.0

index.mddocs/

APISpec

A pluggable API specification generator that enables developers to create OpenAPI (Swagger) specifications programmatically. APISpec supports both OpenAPI 2.x and 3.x formats, integrates with marshmallow schema serialization, provides utilities for parsing docstrings, and offers a flexible plugin architecture for framework integration.

Package Information

  • Package Name: apispec
  • Language: Python
  • Installation: pip install apispec
  • Marshmallow Support: pip install apispec[marshmallow]

Core Imports

from apispec import APISpec, BasePlugin
from apispec.core import Components

For marshmallow integration:

from apispec.ext.marshmallow import MarshmallowPlugin

For utilities:

from apispec.utils import build_reference, trim_docstring, dedent, deepupdate
from apispec.yaml_utils import dict_to_yaml, load_operations_from_docstring

For exceptions:

from apispec.exceptions import (
    APISpecError, PluginMethodNotImplementedError, 
    DuplicateComponentNameError, DuplicateParameterError,
    InvalidParameterError, OpenAPIError
)

Basic Usage

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin

# Create an APISpec instance
spec = APISpec(
    title="My API",
    version="1.0.0", 
    openapi_version="3.0.2",
    plugins=[MarshmallowPlugin()]
)

# Add a schema component
spec.components.schema("User", {
    "type": "object",
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string", "required": True},
        "email": {"type": "string", "format": "email"}
    }
})

# Add a path
spec.path(
    "/users/{id}",
    operations={
        "get": {
            "summary": "Get user by ID",
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": True,
                    "schema": {"type": "integer"}
                }
            ],
            "responses": {
                "200": {
                    "description": "User found",
                    "content": {
                        "application/json": {
                            "schema": {"$ref": "#/components/schemas/User"}
                        }
                    }
                }
            }
        }
    }
)

# Generate the OpenAPI spec
spec_dict = spec.to_dict()
spec_yaml = spec.to_yaml()

Architecture

APISpec uses a flexible, plugin-based architecture that separates core specification generation from framework-specific integrations:

  • APISpec: Main orchestrator that manages specification metadata, components, and paths
  • Components: Manages reusable OpenAPI components (schemas, responses, parameters, security schemes)
  • BasePlugin: Abstract base class providing hooks for custom processing of paths, operations, and components
  • MarshmallowPlugin: Official plugin for converting marshmallow schemas to OpenAPI definitions
  • Helper Methods: Plugin lifecycle methods for processing schemas, parameters, responses, paths, and operations

This design enables APISpec to work with any web framework through plugins while maintaining framework-agnostic core functionality.

Capabilities

Core Specification Management

Central API specification creation and management with support for OpenAPI 2.x and 3.x formats, including specification metadata, path definitions, and output generation.

class APISpec:
    def __init__(
        self,
        title: str,
        version: str, 
        openapi_version: str,
        plugins: Sequence[BasePlugin] = (),
        **options: Any
    ): ...
    
    def to_dict(self) -> dict[str, Any]: ...
    def to_yaml(self, yaml_dump_kwargs: Any | None = None) -> str: ...
    def tag(self, tag: dict) -> APISpec: ...
    def path(
        self,
        path: str | None = None,
        *,
        operations: dict[str, Any] | None = None,
        summary: str | None = None,
        description: str | None = None,
        parameters: list[dict] | None = None,
        **kwargs: Any
    ) -> APISpec: ...

Core Specification

Component Management

Management of reusable OpenAPI components including schemas, responses, parameters, headers, examples, and security schemes with support for lazy registration and reference resolution.

class Components:
    def schema(
        self,
        component_id: str,
        component: dict | None = None,
        *,
        lazy: bool = False,
        **kwargs: Any
    ) -> Components: ...
    
    def response(
        self,
        component_id: str, 
        component: dict | None = None,
        *,
        lazy: bool = False,
        **kwargs: Any
    ) -> Components: ...
    
    def parameter(
        self,
        component_id: str,
        location: str,
        component: dict | None = None,
        *,
        lazy: bool = False,
        **kwargs: Any  
    ) -> Components: ...
    
    def security_scheme(self, component_id: str, component: dict) -> Components: ...

Components

Plugin System

Extensible plugin architecture for integrating with web frameworks and schema libraries, providing lifecycle hooks for processing paths, operations, and components.

class BasePlugin:
    def init_spec(self, spec: APISpec) -> None: ...
    def schema_helper(self, name: str, definition: dict, **kwargs: Any) -> dict | None: ...
    def response_helper(self, response: dict, **kwargs: Any) -> dict | None: ...
    def parameter_helper(self, parameter: dict, **kwargs: Any) -> dict | None: ...
    def header_helper(self, header: dict, **kwargs: Any) -> dict | None: ...
    def path_helper(
        self,
        path: str | None = None,
        operations: dict | None = None,
        parameters: list[dict] | None = None,
        **kwargs: Any
    ) -> str | None: ...
    def operation_helper(
        self,
        path: str | None = None,
        operations: dict | None = None,
        **kwargs: Any
    ) -> None: ...

Plugin System

Marshmallow Integration

Official plugin for converting marshmallow schemas to OpenAPI format with automatic field type mapping, validation constraint extraction, and schema reference management.

class MarshmallowPlugin(BasePlugin):
    def __init__(
        self,
        schema_name_resolver: Callable[[type[Schema]], str] | None = None
    ): ...
    
    def map_to_openapi_type(self, field_cls, *args): ...
    def schema_helper(self, name, _, schema=None, **kwargs): ...
    def parameter_helper(self, parameter, **kwargs): ...
    def response_helper(self, response, **kwargs): ...
    def header_helper(self, header: dict, **kwargs: Any): ...
    def operation_helper(
        self,
        path: str | None = None,
        operations: dict | None = None,
        **kwargs: Any
    ) -> None: ...

def resolver(schema: type[Schema]) -> str: ...
def resolve_schema_instance(
    schema: type[Schema] | Schema | str
) -> Schema: ...
def resolve_schema_cls(
    schema: type[Schema] | str | Schema  
) -> type[Schema] | list[type[Schema]]: ...

Marshmallow Integration

Utilities and YAML Support

Utility functions for OpenAPI reference building, docstring processing, dictionary manipulation, and YAML serialization with docstring parsing capabilities.

def build_reference(
    component_type: str, 
    openapi_major_version: int,
    component_name: str
) -> dict[str, str]: ...

def trim_docstring(docstring: str) -> str: ...
def dedent(content: str) -> str: ...  
def deepupdate(original: dict, update: dict) -> dict: ...

def dict_to_yaml(dic: dict, yaml_dump_kwargs: Any | None = None) -> str: ...
def load_yaml_from_docstring(docstring: str) -> dict: ...
def load_operations_from_docstring(docstring: str) -> dict: ...

Utilities