0
# CLI Commands
1
2
Command-line interface for exporting OpenAPI specifications in JSON or YAML format. Flask-OpenAPI3 provides a Flask CLI command to export the generated OpenAPI specification to files or console output.
3
4
## Capabilities
5
6
### OpenAPI Export Command
7
8
Command for exporting OpenAPI specifications to files or console.
9
10
```python { .api }
11
@click.command(name="openapi")
12
@click.option("--output", "-o", type=click.Path(), help="The output file path.")
13
@click.option("--format", "-f", "_format", type=click.Choice(["json", "yaml"]), help="The output file format.")
14
@click.option("--indent", "-i", type=int, help="The indentation for JSON dumps.")
15
@with_appcontext
16
def openapi_command(output, _format, indent):
17
"""
18
Export the OpenAPI Specification to console or a file.
19
20
Args:
21
output: Output file path (optional, prints to console if not provided)
22
_format: Output format ("json" or "yaml", defaults to json)
23
indent: Indentation level for JSON output (optional)
24
"""
25
```
26
27
## Usage Examples
28
29
### Basic Usage
30
31
Export OpenAPI specification to console:
32
33
```bash
34
# Export to console (JSON format)
35
flask openapi
36
37
# Export to console (YAML format)
38
flask openapi --format yaml
39
```
40
41
### Export to File
42
43
Export specification to files:
44
45
```bash
46
# Export to JSON file
47
flask openapi --output api-spec.json
48
49
# Export to YAML file
50
flask openapi --output api-spec.yaml --format yaml
51
52
# Export with custom indentation
53
flask openapi --output api-spec.json --indent 4
54
```
55
56
### Command Options
57
58
Available command-line options:
59
60
- `--output` / `-o`: Specify output file path
61
- `--format` / `-f`: Choose output format (`json` or `yaml`)
62
- `--indent` / `-i`: Set JSON indentation level
63
64
## Setup and Configuration
65
66
### Flask Application Setup
67
68
To use the CLI command, your Flask-OpenAPI3 application must be properly configured:
69
70
```python
71
from flask_openapi3 import OpenAPI, Info
72
from pydantic import BaseModel
73
74
# Create OpenAPI app
75
info = Info(title="My API", version="1.0.0")
76
app = OpenAPI(__name__, info=info)
77
78
class User(BaseModel):
79
name: str
80
email: str
81
82
@app.get("/users", responses={200: list[User]})
83
def get_users():
84
"""Get all users"""
85
return [{"name": "John", "email": "john@example.com"}]
86
87
if __name__ == "__main__":
88
app.run()
89
```
90
91
### Environment Setup
92
93
Set the Flask application environment variable:
94
95
```bash
96
# Set Flask app
97
export FLASK_APP=myapp.py
98
99
# Or use python -m flask
100
python -m flask openapi --output spec.json
101
```
102
103
### Using with Flask CLI
104
105
The command integrates with Flask's CLI system:
106
107
```bash
108
# List available commands
109
flask --help
110
111
# Get help for openapi command
112
flask openapi --help
113
```
114
115
## Output Formats
116
117
### JSON Output
118
119
Default JSON format output:
120
121
```json
122
{
123
"openapi": "3.1.0",
124
"info": {
125
"title": "My API",
126
"version": "1.0.0"
127
},
128
"paths": {
129
"/users": {
130
"get": {
131
"summary": "Get all users",
132
"operationId": "get_users_get",
133
"responses": {
134
"200": {
135
"description": "Successful Response",
136
"content": {
137
"application/json": {
138
"schema": {
139
"type": "array",
140
"items": {
141
"$ref": "#/components/schemas/User"
142
}
143
}
144
}
145
}
146
}
147
}
148
}
149
}
150
},
151
"components": {
152
"schemas": {
153
"User": {
154
"type": "object",
155
"properties": {
156
"name": {
157
"type": "string"
158
},
159
"email": {
160
"type": "string"
161
}
162
},
163
"required": ["name", "email"]
164
}
165
}
166
}
167
}
168
```
169
170
### YAML Output
171
172
YAML format output (requires PyYAML):
173
174
```yaml
175
openapi: 3.1.0
176
info:
177
title: My API
178
version: 1.0.0
179
paths:
180
/users:
181
get:
182
summary: Get all users
183
operationId: get_users_get
184
responses:
185
'200':
186
description: Successful Response
187
content:
188
application/json:
189
schema:
190
type: array
191
items:
192
$ref: '#/components/schemas/User'
193
components:
194
schemas:
195
User:
196
type: object
197
properties:
198
name:
199
type: string
200
email:
201
type: string
202
required:
203
- name
204
205
```
206
207
## Dependencies
208
209
### Required Dependencies
210
211
The CLI command is available by default with Flask-OpenAPI3 installation.
212
213
### Optional Dependencies
214
215
For YAML output format:
216
217
```bash
218
# Install PyYAML for YAML support
219
pip install pyyaml
220
221
# Or install with optional dependencies
222
pip install flask-openapi3[yaml]
223
```
224
225
## Error Handling
226
227
### Common Issues
228
229
**Application Context Error:**
230
```bash
231
# Error: Working outside of application context
232
flask openapi
233
```
234
235
Solution: Ensure Flask app is properly configured with `FLASK_APP` environment variable.
236
237
**Missing api_doc Attribute:**
238
```bash
239
# Error: No OpenAPI specification found
240
flask openapi
241
```
242
243
Solution: Ensure your application uses OpenAPI class and has defined routes.
244
245
**YAML Format Error:**
246
```bash
247
# Error: pyyaml must be installed
248
flask openapi --format yaml
249
```
250
251
Solution: Install PyYAML dependency.
252
253
### Validation
254
255
The command validates that:
256
1. Flask application context is available
257
2. Application has `api_doc` attribute (OpenAPI specification)
258
3. Required dependencies are installed (PyYAML for YAML format)
259
260
## Integration Examples
261
262
### CI/CD Pipeline
263
264
Use in continuous integration to generate API documentation:
265
266
```bash
267
#!/bin/bash
268
# Generate API specification for documentation
269
flask openapi --output docs/api-spec.json --indent 2
270
271
# Generate YAML for external tools
272
flask openapi --output api-spec.yaml --format yaml
273
```
274
275
### Development Workflow
276
277
Generate specifications during development:
278
279
```bash
280
# Watch for changes and regenerate spec
281
flask openapi --output api-spec.json && echo "Specification updated"
282
```
283
284
### Documentation Generation
285
286
Integrate with documentation tools:
287
288
```bash
289
# Generate spec for Swagger UI
290
flask openapi --output static/swagger.json
291
292
# Generate spec for external documentation
293
flask openapi --output docs/openapi.yaml --format yaml
294
```
295
296
## Advanced Usage
297
298
### Custom Flask CLI Commands
299
300
Extend the CLI with custom commands:
301
302
```python
303
import click
304
from flask import current_app
305
from flask.cli import with_appcontext
306
307
@click.command(name="validate-api")
308
@with_appcontext
309
def validate_api_command():
310
"""Validate OpenAPI specification"""
311
if hasattr(current_app, 'api_doc'):
312
spec = current_app.api_doc
313
# Add custom validation logic
314
click.echo("API specification is valid")
315
else:
316
click.echo("No OpenAPI specification found")
317
318
# Register with Flask app
319
app.cli.add_command(validate_api_command)
320
```
321
322
### Programmatic Access
323
324
Access OpenAPI specification programmatically:
325
326
```python
327
from flask import current_app
328
import json
329
330
def get_openapi_spec():
331
"""Get OpenAPI specification programmatically"""
332
with app.app_context():
333
if hasattr(current_app, 'api_doc'):
334
return current_app.api_doc
335
return None
336
337
# Use in code
338
spec = get_openapi_spec()
339
if spec:
340
with open('spec.json', 'w') as f:
341
json.dump(spec, f, indent=2)
342
```