Connexion 是一个现代化的 Python Web 框架,使规范优先和 API 优先的开发变得简单。 您可以在 [OpenAPI][OpenAPI](或 [Swagger][Swagger])规范中详细描述您的 API, Connexion 将确保它按照您指定的方式运行。
它可以独立运行,也可以与任何兼容 ASGI 或 WSGI 的框架结合使用!
📢 Connexion 3 最近发布了!在此了解更多变更 »
✨ 特性
Connexion 基于您的规范提供以下功能:
- 🚏 自动路由注册,无需
@route
装饰器 - 🔒 身份验证,与应用逻辑分离
- 🔎 请求和响应验证,包括头部、参数和正文
- 📬 参数解析和注入,无需请求对象
- 📨 响应序列化,可以直接返回常规 Python 对象
- 📺 Swagger UI 控制台,带有实时文档和"试一试"功能
- 🧩 可插拔性,在所有维度上
Connexion 还通过提供命令行界面来帮助您编写 OpenAPI 规范并针对它进行开发,让您可以测试和模拟您的规范。
connexion run openapi.yaml
(返回顶部)
🫶 赞助商
赞助商帮助我们投入时间维护 Connexion。想要帮助吗?
(返回顶部)
🪤 为什么选择 Connexion
使用 Connexion,您先编写规范。然后 Connexion 调用您的 Python 代码,处理从规范到代码的映射。这 鼓励您编写规范,使所有开发人员 在编写任何代码之前就能理解您的 API 的功能。
如果多个团队依赖于您的 API,您可以使用 Connexion 轻松 向他们发送 API 文档。这保证了您的 API 将 遵循您编写的规范。这与大多数框架提供的过程不同, 后者是在编写代码后生成规范。 基于代码生成规范的一些缺点是 它们通常缺乏细节或将文档与应用程序的实现 逻辑混合在一起。
(返回顶部)
⚒️ 如何使用
安装
您可以使用 pip 安装 Connexion:
$ pip install connexion
Connexion 提供带有可选依赖项的"extras",以解锁额外功能:
swagger-ui
:为您的应用程序启用 Swagger UI 控制台。uvicorn
:允许使用app.run()
运行您的应用程序进行 开发,而不是使用外部 ASGI 服务器。flask
:启用FlaskApp
以构建与 Flask 生态系统兼容的应用程序。
您可以按以下方式安装它们:
$ pip install connexion[swagger-ui]
$ pip install connexion[swagger-ui,uvicorn]
(返回顶部)
创建您的应用程序
Connexion 可以作为独立应用程序使用,也可以作为中间件包装现有的
使用不同框架编写的 ASGI(或 WSGI)应用程序。独立应用程序可以
使用 AsyncApp
或 FlaskApp
构建。
-
AsyncApp
是一个轻量级应用程序,具有原生异步支持。如果您 正在开始一个新项目,并且没有特定理由使用其他选项,请使用它。from connexion import AsyncApp app = AsyncApp(__name__)
-
FlaskApp
利用Flask
框架,如果您正在从 connexion 2.X 迁移或想要利用Flask
生态系统,这很有用。from connexion import FlaskApp
app = FlaskApp(name)
- `ConnexionMiddleware`可以包装任何现有的ASGI或WSGI应用程序。
如果您已经用其他框架编写了一个应用程序,并希望添加connexion提供的功能,请使用它
```python
from asgi_framework import App
from connexion import ConnexionMiddleware
app = App(__name__)
app = ConnexionMiddleware(app)
(返回顶部)
注册API
虽然您可以在应用程序上注册单个路由,但当您注册由OpenAPI(或Swagger)规范定义的API时,Connexion真正发挥了其优势。
规范中描述的操作通过operationId
自动链接到您的Python视图函数
run.py
def post_greeting(name: str, greeting: str): # 参数会自动解包
return f"{greeting} {name}", 200 # 响应会自动序列化
app.add_api("openapi.yaml")
openapi.yaml
...
paths:
/greeting/{name}:
post:
operationId: run.post_greeting
responses:
200:
content:
text/plain:
schema:
type: string
parameters:
- name: name
in: path
required: true
schema:
type: string
- name: greeting
in: query
required: true
schema:
type: string
(返回顶部)
运行您的应用程序
如果您使用connexion[uvicorn]
安装了connexion,可以使用run
方法运行它。这仅推荐用于开发:
app.run()
在生产环境中,使用ASGI服务器(如uvicorn
)运行您的应用程序。如果您在名为run.py
的Python模块中定义了app
,可以按如下方式运行:
$ uvicorn run:app
或者使用gunicorn:
$ gunicorn -k uvicorn.workers.UvicornWorker run:app
现在您可以运行和使用Connexion了!
查看[examples][examples]文件夹获取更多示例。
(返回顶部)
📜 变更
完整的更新日志维护在[GitHub发布页面][Releases]。
(返回顶部)
🤲 贡献
我们欢迎您的想法、问题和拉取请求。只需遵循常规/标准的GitHub做法即可。
为了便于开发,请使用poetry安装connexion及其所有额外功能,并安装pre-commit钩子以自动运行black格式化和静态分析检查。
pip install poetry
poetry install --all-extras
pre-commit install
通过查看我们的[架构][Architecture],您可以了解更多关于Connexion如何工作以及在哪里应用您的更改。
除非您事先明确声明,否则您有意提交以包含在本项目中的任何非微不足道的贡献,均应遵守以下所写的Apache License 2.0的条款和条件,不附加任何额外的版权信息、条款或条件。
(返回顶部)
🙏 致谢
我们要感谢Connexion的所有贡献者参与这个项目,感谢Swagger/OpenAPI的支持,以及感谢Zalando最初开发和发布Connexion。
📚 推荐资源
关于规范优先工作方式的优势:
- [Atlassian博客][Blog Atlassian]
- [Zalando API指南][API guidelines Zalando]
- [ML6博客][Blog ML6]
- [Zalando博客][Blog Zalando]
帮助您进行规范优先工作的工具:
- [在线Swagger编辑器][Online swagger editor]
- [VS Code插件][VS Code plugin]
- [PyCharm插件][Pycharm plugin]