0
# CLI Tools
1

2
Command-line interface for running development servers and managing Connexion applications. The CLI provides a convenient way to quickly start API servers directly from OpenAPI specifications.
3

4
## Capabilities
5

6
### Main Command
7

8
Entry point for the Connexion command-line interface.
9

10
```python { .api }
11
from connexion.cli import main, create_app
12

13
def main(argv: list = None) -> None:
14
    """
15
    Main CLI entry point.
16
    
17
    Parameters:
18
    - argv: Command line arguments (defaults to sys.argv[1:])
19
    """
20
```
21

22
### Run Command
23

24
Primary command for running OpenAPI specifications as web servers.
25

26
```bash
27
connexion run <spec_file> [base_module_path] [options]
28
```
29

30
### Command Arguments
31

32
```python { .api }
33
# Positional Arguments
34
spec_file: str          # Path to OpenAPI specification file or URL
35
base_module_path: str   # Root directory of handler code (optional)
36

37
# Server Options
38
--port, -p: int         # Port to listen on (default: 5000)
39
--host, -H: str         # Host interface to bind on (default: 127.0.0.1)
40
--app-framework, -f: str # App framework: 'async' or 'flask' (default: async)
41

42
# Development Options
43
--stub: bool            # Return 501 for unimplemented endpoints
44
--mock: str             # Return example data: 'all' or 'notimplemented'
45
--verbose, -v: int      # Verbosity level (0-2, use multiple -v for more verbose)
46

47
# Swagger UI Options
48
--swagger-ui-path: str         # URL path for API console (default: /ui)
49
--swagger-ui-template-dir: str # Path to custom UI template directory
50

51
# API Options
52
--base-path: str           # Override basePath from spec
53
--auth-all-paths: bool     # Enable auth for paths not in spec
54
--validate-responses: bool # Enable response validation
55
--strict-validation: bool  # Enable strict request validation
56

57
# General Options
58
--version: bool            # Show version information
59
--help: bool              # Show help message
60
```
61

62
### Application Factory
63

64
Function for creating Connexion applications from CLI arguments.
65

66
```python { .api }
67
def create_app(args: argparse.Namespace = None) -> AbstractApp:
68
    """
69
    Create Connexion application from CLI arguments.
70
    
71
    Parameters:
72
    - args: Parsed command line arguments
73
    
74
    Returns:
75
    AbstractApp: Configured Connexion application
76
    """
77
```
78

79
### Available App Frameworks
80

81
```python { .api }
82
AVAILABLE_APPS = {
83
    'async': 'connexion.apps.asynchronous.AsyncApp',  # Default
84
    'flask': 'connexion.apps.flask.FlaskApp'
85
}
86
```
87

88
## Usage Examples
89

90
### Basic Usage
91

92
```bash
93
# Run OpenAPI spec with AsyncApp (default)
94
connexion run openapi.yaml
95

96
# Run with Flask framework
97
connexion run openapi.yaml --app-framework flask
98

99
# Run on custom host and port
100
connexion run openapi.yaml --host 0.0.0.0 --port 8080
101
```
102

103
### Development Features
104

105
```bash
106
# Enable stub responses for unimplemented endpoints
107
connexion run openapi.yaml --stub
108

109
# Mock all endpoints with example data
110
connexion run openapi.yaml --mock all
111

112
# Mock only unimplemented endpoints
113
connexion run openapi.yaml --mock notimplemented
114

115
# Enable verbose logging
116
connexion run openapi.yaml -v      # INFO level
117
connexion run openapi.yaml -vv     # DEBUG level
118
```
119

120
### Swagger UI Configuration
121

122
```bash
123
# Custom Swagger UI path
124
connexion run openapi.yaml --swagger-ui-path /docs
125

126
# Custom Swagger UI template directory
127
connexion run openapi.yaml --swagger-ui-template-dir ./custom-ui
128

129
# Disable Swagger UI by setting empty path
130
connexion run openapi.yaml --swagger-ui-path ""
131
```
132

133
### Validation Options
134

135
```bash
136
# Enable strict request validation
137
connexion run openapi.yaml --strict-validation
138

139
# Enable response validation
140
connexion run openapi.yaml --validate-responses
141

142
# Enable all validation options
143
connexion run openapi.yaml --strict-validation --validate-responses
144
```
145

146
### Remote Specifications
147

148
```bash
149
# Run from remote OpenAPI specification
150
connexion run https://api.example.com/openapi.yaml
151

152
# Run from GitHub raw file
153
connexion run https://raw.githubusercontent.com/user/repo/main/openapi.yaml
154
```
155

156
### Module Path Configuration
157

158
```bash
159
# Specify handler module path
160
connexion run api/openapi.yaml api/handlers
161

162
# OpenAPI spec in different directory
163
connexion run specs/api.yaml src/
164

165
# Current directory as module path
166
connexion run openapi.yaml .
167
```
168

169
### Advanced Configuration
170

171
```bash
172
# Override base path from specification
173
connexion run openapi.yaml --base-path /v2
174

175
# Enable authentication for all paths
176
connexion run openapi.yaml --auth-all-paths
177

178
# Combination of development options
179
connexion run openapi.yaml \
180
  --mock notimplemented \
181
  --strict-validation \
182
  --validate-responses \
183
  --verbose \
184
  --swagger-ui-path /api-docs
185
```
186

187
### Production-like Setup
188

189
```bash
190
# Production-ready configuration
191
connexion run openapi.yaml \
192
  --host 0.0.0.0 \
193
  --port 8000 \
194
  --app-framework async \
195
  --strict-validation \
196
  --validate-responses \
197
  --auth-all-paths
198
```
199

200
### Mock Development Server
201

202
```bash
203
# Complete mock server for API development
204
connexion run openapi.yaml \
205
  --mock all \
206
  --swagger-ui-path /docs \
207
  --verbose
208
```
209

210
### Using with Docker
211

212
```dockerfile
213
# Dockerfile example
214
FROM python:3.11
215
WORKDIR /app
216
COPY requirements.txt .
217
RUN pip install -r requirements.txt
218
COPY . .
219
EXPOSE 8080
220
CMD ["connexion", "run", "openapi.yaml", "--host", "0.0.0.0", "--port", "8080"]
221
```
222

223
### Environment Integration
224

225
```bash
226
#!/bin/bash
227
# Development script
228
export CONNEXION_HOST=${HOST:-127.0.0.1}
229
export CONNEXION_PORT=${PORT:-5000}
230
export CONNEXION_VERBOSE=${VERBOSE:-1}
231

232
connexion run openapi.yaml \
233
  --host $CONNEXION_HOST \
234
  --port $CONNEXION_PORT \
235
  --verbose $CONNEXION_VERBOSE \
236
  --mock notimplemented \
237
  --swagger-ui-path /ui
238
```
239

240
### Custom Factory Usage
241

242
```python
243
# custom_server.py
244
from connexion.cli import create_app
245
import argparse
246

247
# Create custom args
248
args = argparse.Namespace(
249
    spec_file='api.yaml',
250
    base_module_path=None,
251
    port=8000,
252
    host='0.0.0.0',
253
    app_framework='async',
254
    stub=False,
255
    mock=None,
256
    swagger_ui_path='/docs',
257
    swagger_ui_template_dir=None,
258
    auth_all_paths=True,
259
    validate_responses=True,
260
    strict_validation=True,
261
    verbose=1,
262
    base_path=None
263
)
264

265
# Create and configure app
266
app = create_app(args)
267

268
# Add custom configuration
269
if hasattr(app, 'app'):  # Flask app
270
    app.app.config['CUSTOM_SETTING'] = 'value'
271

272
# Run with custom logic
273
if __name__ == '__main__':
274
    app.run(host=args.host, port=args.port)
275
```
276

277
### Version Information
278

279
```bash
280
# Show Connexion version
281
connexion --version
282

283
# Example output:
284
# Connexion 3.2.0
285
```
286

287
### Help and Documentation
288

289
```bash
290
# Show general help
291
connexion --help
292

293
# Show run command help
294
connexion run --help
295
```
296

297
## Integration Examples
298

299
### CI/CD Pipeline
300

301
```yaml
302
# .github/workflows/api-test.yml
303
name: API Testing
304
on: [push, pull_request]
305

306
jobs:
307
  test:
308
    runs-on: ubuntu-latest
309
    steps:
310
      - uses: actions/checkout@v2
311
      - uses: actions/setup-python@v2
312
        with:
313
          python-version: '3.11'
314
      
315
      - name: Install dependencies
316
        run: |
317
          pip install connexion[swagger-ui]
318
          
319
      - name: Start API server
320
        run: |
321
          connexion run openapi.yaml --mock all --port 8080 &
322
          sleep 5
323
          
324
      - name: Test API endpoints
325
        run: |
326
          curl -f http://localhost:8080/health
327
          curl -f http://localhost:8080/ui/
328
```
329

330
### Docker Compose
331

332
```yaml
333
# docker-compose.yml
334
version: '3.8'
335
services:
336
  api:
337
    build: .
338
    ports:
339
      - "8080:8080"
340
    command: >
341
      connexion run openapi.yaml
342
      --host 0.0.0.0
343
      --port 8080
344
      --validate-responses
345
      --strict-validation
346
    environment:
347
      - CONNEXION_VERBOSE=1
348
    volumes:
349
      - ./api:/app/api
350
      - ./openapi.yaml:/app/openapi.yaml
351
```