0
# Core Specification Management
1
2
Central API specification creation and management with support for OpenAPI 2.x and 3.x formats. The APISpec class serves as the main orchestrator for building OpenAPI specifications programmatically.
3
4
## Capabilities
5
6
### APISpec Class
7
8
Main class for creating and managing OpenAPI specifications. Handles specification metadata, component management, path definitions, and output generation.
9
10
```python { .api }
11
class APISpec:
12
def __init__(
13
self,
14
title: str,
15
version: str,
16
openapi_version: str,
17
plugins: Sequence[BasePlugin] = (),
18
**options: Any
19
):
20
"""
21
Create a new APISpec instance.
22
23
Parameters:
24
- title: API title
25
- version: API version
26
- openapi_version: OpenAPI Specification version ('2.x' or '3.x.x')
27
- plugins: Plugin instances for framework integration
28
- **options: Additional top-level OpenAPI fields
29
"""
30
```
31
32
### Specification Output
33
34
Generate the final OpenAPI specification in dictionary or YAML format for consumption by OpenAPI tools and documentation generators.
35
36
```python { .api }
37
def to_dict(self) -> dict[str, Any]:
38
"""
39
Return the specification as a dictionary.
40
41
Returns:
42
Dictionary containing the complete OpenAPI specification
43
"""
44
45
def to_yaml(self, yaml_dump_kwargs: Any | None = None) -> str:
46
"""
47
Render the specification to YAML string.
48
49
Parameters:
50
- yaml_dump_kwargs: Additional arguments to pass to yaml.dump
51
52
Returns:
53
YAML string representation of the specification
54
"""
55
```
56
57
### Tag Management
58
59
Add tag information to organize and categorize API operations in the generated specification.
60
61
```python { .api }
62
def tag(self, tag: dict) -> APISpec:
63
"""
64
Store information about a tag.
65
66
Parameters:
67
- tag: Dictionary containing tag information (name, description, etc.)
68
69
Returns:
70
Self for method chaining
71
"""
72
```
73
74
### Path Definition
75
76
Add path objects (endpoints) to the specification with HTTP operations, parameters, and responses.
77
78
```python { .api }
79
def path(
80
self,
81
path: str | None = None,
82
*,
83
operations: dict[str, Any] | None = None,
84
summary: str | None = None,
85
description: str | None = None,
86
parameters: list[dict] | None = None,
87
**kwargs: Any
88
) -> APISpec:
89
"""
90
Add a new path object to the specification.
91
92
Parameters:
93
- path: URL path component (e.g., '/users/{id}')
94
- operations: Dictionary mapping HTTP methods to operation objects
95
- summary: Short summary relevant to all operations in this path
96
- description: Long description relevant to all operations in this path
97
- parameters: List of parameters relevant to all operations in this path
98
- **kwargs: Parameters used by path helpers from plugins
99
100
Returns:
101
Self for method chaining
102
"""
103
```
104
105
## Properties
106
107
### Core Properties
108
109
Access to specification metadata and configuration.
110
111
```python { .api }
112
title: str # API title
113
version: str # API version
114
openapi_version: Version # OpenAPI version object
115
plugins: Sequence[BasePlugin] # Registered plugins
116
options: dict # Additional top-level options
117
components: Components # Component management instance
118
```
119
120
## Constants
121
122
OpenAPI version and method validation constants.
123
124
```python { .api }
125
VALID_METHODS_OPENAPI_V2: list[str] # ['get', 'post', 'put', 'patch', 'delete', 'head', 'options']
126
VALID_METHODS_OPENAPI_V3: list[str] # VALID_METHODS_OPENAPI_V2 + ['trace']
127
VALID_METHODS: dict[int, list[str]] # {2: VALID_METHODS_OPENAPI_V2, 3: VALID_METHODS_OPENAPI_V3}
128
MIN_INCLUSIVE_OPENAPI_VERSION: Version # Version("2.0")
129
MAX_EXCLUSIVE_OPENAPI_VERSION: Version # Version("4.0")
130
```
131
132
## Usage Examples
133
134
### Creating a Basic Specification
135
136
```python
137
from apispec import APISpec
138
139
# Create OpenAPI 3.0 specification
140
spec = APISpec(
141
title="Pet Store API",
142
version="1.0.0",
143
openapi_version="3.0.2",
144
info={
145
"description": "A simple pet store API",
146
"contact": {"name": "API Support", "email": "support@petstore.com"}
147
}
148
)
149
150
# Add tags for organization
151
spec.tag({
152
"name": "pets",
153
"description": "Operations on pets"
154
})
155
```
156
157
### Adding Paths with Operations
158
159
```python
160
# Add a path with multiple operations
161
spec.path(
162
"/pets",
163
operations={
164
"get": {
165
"tags": ["pets"],
166
"summary": "List all pets",
167
"parameters": [
168
{
169
"name": "limit",
170
"in": "query",
171
"schema": {"type": "integer", "maximum": 100}
172
}
173
],
174
"responses": {
175
"200": {
176
"description": "List of pets",
177
"content": {
178
"application/json": {
179
"schema": {
180
"type": "array",
181
"items": {"$ref": "#/components/schemas/Pet"}
182
}
183
}
184
}
185
}
186
}
187
},
188
"post": {
189
"tags": ["pets"],
190
"summary": "Create a pet",
191
"requestBody": {
192
"required": True,
193
"content": {
194
"application/json": {
195
"schema": {"$ref": "#/components/schemas/Pet"}
196
}
197
}
198
},
199
"responses": {
200
"201": {"description": "Pet created"},
201
"400": {"description": "Invalid input"}
202
}
203
}
204
}
205
)
206
```
207
208
### Generating Output
209
210
```python
211
# Get specification as dictionary
212
spec_dict = spec.to_dict()
213
214
# Get specification as YAML
215
spec_yaml = spec.to_yaml()
216
217
# Custom YAML options
218
spec_yaml_custom = spec.to_yaml({
219
"sort_keys": True,
220
"indent": 4
221
})
222
```