apispec

What it is and what it does

apispec is a code-driven OpenAPI specification generator that converts Python code into machine-readable API documentation. It works by introspecting your code—particularly route handlers, schemas, and security definitions—and synthesizing them into valid OpenAPI 2 or 3 documents that can be exported as JSON or YAML. The package is framework-agnostic at its core but ships with built-in support for marshmallow schema serialization, and integrates with web frameworks through optional plugins.

Typical usage involves instantiating an APISpec object with your target OpenAPI version, registering plugins for your framework and schema library, then feeding it your application's routes and models. It parses docstring annotations (YAML-formatted operation metadata) and automatically generates schema definitions, security schemes, and endpoint documentation. This keeps your spec in sync with your code rather than maintaining separate documentation files.

Use it for:

• Generate interactive API documentation (Swagger UI, ReDoc) from Flask or other framework route definitions without manual YAML
• Maintain OpenAPI specs that stay synchronized with marshmallow schema changes during development
• Export API contracts for client code generation or third-party API integration testing
• Publish machine-readable API definitions for API gateways, monitoring tools, or developer portals
• Validate request/response schemas at runtime by embedding OpenAPI definitions in your application

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Generates OpenAPI specification documents from Python code, supporting versions 2 and 3 of the OpenAPI standard with framework-agnostic design and built-in marshmallow integration.

Yes. apispec is production-stable (Development Status 5), actively maintained, has no known vulnerabilities, and solves a real problem—keeping API documentation synchronized with code. The single dependency and low install friction make it a safe addition. Install it if you need OpenAPI specs for a Python web service and want to avoid manual YAML maintenance.

Install

apispec on PyPI

pip install apispec

uv add apispec

poetry add apispec

Installing apispec

Before you install

Low install friction with a single runtime dependency (packaging). Active maintenance with recent releases; last commit 2026-08-03 and 1218 GitHub stars indicate ongoing support.

License in practice

MIT licensed under permissive terms, allowing free use, modification, and distribution with minimal restrictions.

Quickstart

pip install apispec

from apispec import APISpec
spec = APISpec(
    title="My API",
    version="1.0.0",
    openapi_version="3.0.2"
)
print(spec.to_dict())

Requires Python 3.10 or later.

Verify before relying

• Whether the package supports automatic extraction of endpoint documentation from all major Python web frameworks beyond Flask
• Performance characteristics when generating specs for large APIs with hundreds of endpoints
• Extent of marshmallow schema inference capabilities and any limitations in complex nested structures

Package facts

Evidence: apispec-6.10.0-py3-none-any.whl

Keywords: apispec, swagger, openapi, specification, oas, documentation, spec, rest, api

Tags

More Documentation packages