0
# Connexion
1

2
Connexion is a Python framework that automagically handles HTTP requests based on OpenAPI Specification (formerly known as Swagger Spec) of your API described in YAML/JSON format. Connexion allows you to write an OpenAPI specification first, then maps the endpoints to your Python functions, making it unique as many tools generate the specification based on your Python code. You can describe your REST API in as much detail as you want; then Connexion guarantees that it will work as you specified.
3

4
## Package Information
5

6
- **Package Name**: connexion
7
- **Language**: Python  
8
- **Installation**: `pip install connexion`
9
- **Extras**: `pip install connexion[flask]` for Flask support, `pip install connexion[swagger-ui]` for Swagger UI, `pip install connexion[uvicorn]` for production ASGI server
10

11
## Core Imports
12

13
```python
14
import connexion
15
```
16

17
For AsyncApp (recommended for new projects):
18
```python
19
from connexion import AsyncApp
20
```
21

22
For Flask compatibility:
23
```python
24
from connexion import FlaskApp
25
```
26

27
For middleware integration:
28
```python
29
from connexion import ConnexionMiddleware
30
```
31

32
## Basic Usage
33

34
### AsyncApp (Native ASGI)
35

36
```python
37
from connexion import AsyncApp
38

39
# Create async application
40
app = AsyncApp(__name__)
41

42
# Add OpenAPI specification
43
app.add_api('openapi.yaml')
44

45
# Run with uvicorn
46
if __name__ == '__main__':
47
    app.run(host='0.0.0.0', port=8080)
48
```
49

50
### FlaskApp (WSGI Compatibility)
51

52
```python
53
from connexion import FlaskApp
54

55
# Create Flask-based application
56
app = FlaskApp(__name__)
57

58
# Add OpenAPI specification  
59
app.add_api('openapi.yaml')
60

61
# Access underlying Flask app if needed
62
flask_app = app.app
63

64
# Run development server
65
if __name__ == '__main__':
66
    app.run(host='0.0.0.0', port=8080, debug=True)
67
```
68

69
### ASGI Middleware Integration
70

71
```python
72
from connexion import ConnexionMiddleware
73
from starlette.applications import Starlette
74

75
# Add Connexion to existing ASGI app
76
asgi_app = Starlette()
77
app = ConnexionMiddleware(asgi_app)
78
app.add_api('openapi.yaml')
79
```
80

81
## Architecture
82

83
Connexion implements a layered architecture that separates OpenAPI specification handling from the underlying web framework:
84

85
- **Application Layer**: `AsyncApp`, `FlaskApp` provide framework-specific implementations
86
- **Middleware Layer**: Request/response processing, validation, security, routing  
87
- **Operation Layer**: Maps OpenAPI operations to Python functions via resolvers
88
- **Validation Layer**: Automatic request/response validation based on OpenAPI schema
89
- **Security Layer**: Built-in authentication/authorization handlers
90

91
This design enables spec-first development where the OpenAPI specification serves as the single source of truth for API behavior, with automatic generation of route handlers, parameter validation, response serialization, and interactive documentation.
92

93
## Capabilities
94

95
### Application Classes
96

97
Core application classes for creating Connexion-based web services with different underlying frameworks and deployment models.
98

99
```python { .api }
100
class AsyncApp:
101
    def __init__(self, import_name: str, **kwargs): ...
102
    def add_api(self, specification: str, **kwargs): ...
103
    def run(self, host: str = None, port: int = None, **options): ...
104

105
class FlaskApp:
106
    def __init__(self, import_name: str, **kwargs): ...
107
    def add_api(self, specification: str, **kwargs): ...
108
    def run(self, host: str = None, port: int = None, **options): ...
109

110
class ConnexionMiddleware:
111
    def __init__(self, app, **kwargs): ...
112
    def add_api(self, specification: str, **kwargs): ...
113
```
114

115
[Application Classes](./applications.md)
116

117
### Request/Response Handling
118

119
Comprehensive middleware system for processing HTTP requests and responses with automatic validation, serialization, and error handling based on OpenAPI specifications.
120

121
```python { .api }
122
class ConnexionRequest:
123
    async def get_body(self): ...
124
    async def json(self): ...
125
    async def form(self) -> dict: ...
126
    async def files(self) -> dict: ...
127
    @property
128
    def query_params(self) -> dict: ...
129
    @property
130
    def path_params(self) -> dict: ...
131

132
class ConnexionResponse:
133
    def __init__(self, body, status_code: int = 200, headers: dict = None): ...
134

135
def problem(status: int, title: str, detail: str = None, **kwargs): ...
136
```
137

138
[Request Response](./request-response.md)
139

140
### Operation Resolution
141

142
System for mapping OpenAPI operations to Python functions using various resolution strategies for flexible endpoint handling.
143

144
```python { .api }
145
class Resolver:
146
    def __init__(self, function_resolver=None): ...
147
    def resolve(self, operation): ...
148

149
class RestyResolver:
150
    def __init__(self, default_module_name: str, **kwargs): ...
151

152
class MethodResolver:
153
    def __init__(self, api_name: str, **kwargs): ...
154
```
155

156
[Operation Resolution](./operation-resolution.md)
157

158
### Validation System
159

160
Automatic request and response validation based on OpenAPI schema definitions with support for various content types and validation strategies.
161

162
```python { .api }
163
VALIDATOR_MAP: dict
164
class AbstractRequestBodyValidator: ...
165
class AbstractParameterValidator: ...
166
class AbstractResponseBodyValidator: ...
167
```
168

169
[Validation](./validation.md)
170

171
### Security & Authentication
172

173
Built-in security handlers for common authentication methods with support for Bearer tokens, Basic auth, API keys, and OAuth2.
174

175
```python { .api }
176
def bearer_auth(token: str): ...
177
def basic_auth(username: str, password: str): ...
178
def api_key_auth(api_key: str, required_scopes: list): ...
179
```
180

181
[Security](./security.md)
182

183
### Exception Handling
184

185
Comprehensive exception system following RFC 7807 Problem Details standard for consistent error responses and debugging.
186

187
```python { .api }
188
class ProblemException(Exception):
189
    def __init__(self, status: int, title: str, detail: str = None, **kwargs): ...
190

191
class BadRequestProblem(ProblemException): ...
192
class UnauthorizedProblem(ProblemException): ...
193
class ForbiddenProblem(ProblemException): ...
194
```
195

196
[Exceptions](./exceptions.md)
197

198
### CLI Tools
199

200
Command-line interface for running development servers and managing Connexion applications.
201

202
```python { .api }
203
# Command: connexion run <spec_file>
204
def main(): ...
205
```
206

207
[CLI](./cli.md)
208

209
## Types
210

211
```python { .api }
212
# Request/Response Types
213
MaybeAwaitable = Union[T, Awaitable[T]]
214
WSGIApp = Callable[[dict, Callable], Iterable[bytes]]
215
ASGIApp = Callable[[dict, Callable, Callable], Awaitable[None]]
216

217
# Data Structures
218
class NoContent:
219
    """Represents empty HTTP response body"""
220
    pass
221

222
class MediaTypeDict(dict):
223
    """Media type mapping utilities"""
224
    pass
225
```