0
# APISpec
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: apispec
7
- **Language**: Python
8
- **Installation**: `pip install apispec`
9
- **Marshmallow Support**: `pip install apispec[marshmallow]`
10
11
## Core Imports
12
13
```python
14
from apispec import APISpec, BasePlugin
15
from apispec.core import Components
16
```
17
18
For marshmallow integration:
19
20
```python
21
from apispec.ext.marshmallow import MarshmallowPlugin
22
```
23
24
For utilities:
25
26
```python
27
from apispec.utils import build_reference, trim_docstring, dedent, deepupdate
28
from apispec.yaml_utils import dict_to_yaml, load_operations_from_docstring
29
```
30
31
For exceptions:
32
33
```python
34
from apispec.exceptions import (
35
APISpecError, PluginMethodNotImplementedError,
36
DuplicateComponentNameError, DuplicateParameterError,
37
InvalidParameterError, OpenAPIError
38
)
39
```
40
41
## Basic Usage
42
43
```python
44
from apispec import APISpec
45
from apispec.ext.marshmallow import MarshmallowPlugin
46
47
# Create an APISpec instance
48
spec = APISpec(
49
title="My API",
50
version="1.0.0",
51
openapi_version="3.0.2",
52
plugins=[MarshmallowPlugin()]
53
)
54
55
# Add a schema component
56
spec.components.schema("User", {
57
"type": "object",
58
"properties": {
59
"id": {"type": "integer"},
60
"name": {"type": "string", "required": True},
61
"email": {"type": "string", "format": "email"}
62
}
63
})
64
65
# Add a path
66
spec.path(
67
"/users/{id}",
68
operations={
69
"get": {
70
"summary": "Get user by ID",
71
"parameters": [
72
{
73
"name": "id",
74
"in": "path",
75
"required": True,
76
"schema": {"type": "integer"}
77
}
78
],
79
"responses": {
80
"200": {
81
"description": "User found",
82
"content": {
83
"application/json": {
84
"schema": {"$ref": "#/components/schemas/User"}
85
}
86
}
87
}
88
}
89
}
90
}
91
)
92
93
# Generate the OpenAPI spec
94
spec_dict = spec.to_dict()
95
spec_yaml = spec.to_yaml()
96
```
97
98
## Architecture
99
100
APISpec uses a flexible, plugin-based architecture that separates core specification generation from framework-specific integrations:
101
102
- **APISpec**: Main orchestrator that manages specification metadata, components, and paths
103
- **Components**: Manages reusable OpenAPI components (schemas, responses, parameters, security schemes)
104
- **BasePlugin**: Abstract base class providing hooks for custom processing of paths, operations, and components
105
- **MarshmallowPlugin**: Official plugin for converting marshmallow schemas to OpenAPI definitions
106
- **Helper Methods**: Plugin lifecycle methods for processing schemas, parameters, responses, paths, and operations
107
108
This design enables APISpec to work with any web framework through plugins while maintaining framework-agnostic core functionality.
109
110
## Capabilities
111
112
### Core Specification Management
113
114
Central API specification creation and management with support for OpenAPI 2.x and 3.x formats, including specification metadata, path definitions, and output generation.
115
116
```python { .api }
117
class APISpec:
118
def __init__(
119
self,
120
title: str,
121
version: str,
122
openapi_version: str,
123
plugins: Sequence[BasePlugin] = (),
124
**options: Any
125
): ...
126
127
def to_dict(self) -> dict[str, Any]: ...
128
def to_yaml(self, yaml_dump_kwargs: Any | None = None) -> str: ...
129
def tag(self, tag: dict) -> APISpec: ...
130
def path(
131
self,
132
path: str | None = None,
133
*,
134
operations: dict[str, Any] | None = None,
135
summary: str | None = None,
136
description: str | None = None,
137
parameters: list[dict] | None = None,
138
**kwargs: Any
139
) -> APISpec: ...
140
```
141
142
[Core Specification](./core-spec.md)
143
144
### Component Management
145
146
Management of reusable OpenAPI components including schemas, responses, parameters, headers, examples, and security schemes with support for lazy registration and reference resolution.
147
148
```python { .api }
149
class Components:
150
def schema(
151
self,
152
component_id: str,
153
component: dict | None = None,
154
*,
155
lazy: bool = False,
156
**kwargs: Any
157
) -> Components: ...
158
159
def response(
160
self,
161
component_id: str,
162
component: dict | None = None,
163
*,
164
lazy: bool = False,
165
**kwargs: Any
166
) -> Components: ...
167
168
def parameter(
169
self,
170
component_id: str,
171
location: str,
172
component: dict | None = None,
173
*,
174
lazy: bool = False,
175
**kwargs: Any
176
) -> Components: ...
177
178
def security_scheme(self, component_id: str, component: dict) -> Components: ...
179
```
180
181
[Components](./components.md)
182
183
### Plugin System
184
185
Extensible plugin architecture for integrating with web frameworks and schema libraries, providing lifecycle hooks for processing paths, operations, and components.
186
187
```python { .api }
188
class BasePlugin:
189
def init_spec(self, spec: APISpec) -> None: ...
190
def schema_helper(self, name: str, definition: dict, **kwargs: Any) -> dict | None: ...
191
def response_helper(self, response: dict, **kwargs: Any) -> dict | None: ...
192
def parameter_helper(self, parameter: dict, **kwargs: Any) -> dict | None: ...
193
def header_helper(self, header: dict, **kwargs: Any) -> dict | None: ...
194
def path_helper(
195
self,
196
path: str | None = None,
197
operations: dict | None = None,
198
parameters: list[dict] | None = None,
199
**kwargs: Any
200
) -> str | None: ...
201
def operation_helper(
202
self,
203
path: str | None = None,
204
operations: dict | None = None,
205
**kwargs: Any
206
) -> None: ...
207
```
208
209
[Plugin System](./plugin-system.md)
210
211
### Marshmallow Integration
212
213
Official plugin for converting marshmallow schemas to OpenAPI format with automatic field type mapping, validation constraint extraction, and schema reference management.
214
215
```python { .api }
216
class MarshmallowPlugin(BasePlugin):
217
def __init__(
218
self,
219
schema_name_resolver: Callable[[type[Schema]], str] | None = None
220
): ...
221
222
def map_to_openapi_type(self, field_cls, *args): ...
223
def schema_helper(self, name, _, schema=None, **kwargs): ...
224
def parameter_helper(self, parameter, **kwargs): ...
225
def response_helper(self, response, **kwargs): ...
226
def header_helper(self, header: dict, **kwargs: Any): ...
227
def operation_helper(
228
self,
229
path: str | None = None,
230
operations: dict | None = None,
231
**kwargs: Any
232
) -> None: ...
233
234
def resolver(schema: type[Schema]) -> str: ...
235
def resolve_schema_instance(
236
schema: type[Schema] | Schema | str
237
) -> Schema: ...
238
def resolve_schema_cls(
239
schema: type[Schema] | str | Schema
240
) -> type[Schema] | list[type[Schema]]: ...
241
```
242
243
[Marshmallow Integration](./marshmallow.md)
244
245
### Utilities and YAML Support
246
247
Utility functions for OpenAPI reference building, docstring processing, dictionary manipulation, and YAML serialization with docstring parsing capabilities.
248
249
```python { .api }
250
def build_reference(
251
component_type: str,
252
openapi_major_version: int,
253
component_name: str
254
) -> dict[str, str]: ...
255
256
def trim_docstring(docstring: str) -> str: ...
257
def dedent(content: str) -> str: ...
258
def deepupdate(original: dict, update: dict) -> dict: ...
259
260
def dict_to_yaml(dic: dict, yaml_dump_kwargs: Any | None = None) -> str: ...
261
def load_yaml_from_docstring(docstring: str) -> dict: ...
262
def load_operations_from_docstring(docstring: str) -> dict: ...
263
```
264
265
[Utilities](./utils.md)