connexion

Connexion 是一个现代化的 Python Web 框架，使规范优先和 API 优先的开发变得简单。您可以在 [OpenAPI][OpenAPI]（或 [Swagger][Swagger]）规范中详细描述您的 API， Connexion 将确保它按照您指定的方式运行。

它可以独立运行，也可以与任何兼容 ASGI 或 WSGI 的框架结合使用！

<a href="https://connexion.readthedocs.io/en/latest/v3.html">📢 Connexion 3 最近发布了！在此了解更多变更 »</a>

✨ 特性

Connexion 基于您的规范提供以下功能：

🚏 自动路由注册，无需 @route 装饰器
🔒 身份验证，与应用逻辑分离
🔎 请求和响应验证，包括头部、参数和正文
📬 参数解析和注入，无需请求对象
📨 响应序列化，可以直接返回常规 Python 对象
📺 Swagger UI 控制台，带有实时文档和"试一试"功能
🧩 可插拔性，在所有维度上

Connexion 还通过提供命令行界面来帮助您编写 OpenAPI 规范并针对它进行开发，让您可以测试和模拟您的规范。

   connexion run openapi.yaml

(<a href="#top">返回顶部</a>)

🫶 赞助商

赞助商帮助我们投入时间维护 Connexion。想要帮助吗？

(<a href="#top">返回顶部</a>)

🪤 为什么选择 Connexion

使用 Connexion，您先编写规范。然后 Connexion 调用您的 Python 代码，处理从规范到代码的映射。这鼓励您编写规范，使所有开发人员在编写任何代码之前就能理解您的 API 的功能。

如果多个团队依赖于您的 API，您可以使用 Connexion 轻松向他们发送 API 文档。这保证了您的 API 将遵循您编写的规范。这与大多数框架提供的过程不同，后者是在编写代码后生成规范。基于代码生成规范的一些缺点是它们通常缺乏细节或将文档与应用程序的实现逻辑混合在一起。

(<a href="#top">返回顶部</a>)

⚒️ 如何使用

安装

您可以使用 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]

(<a href="#top">返回顶部</a>)

创建您的应用程序

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)

(<a href="#top">返回顶部</a>)

注册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

(<a href="#top">返回顶部</a>)

运行您的应用程序

如果您使用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]文件夹获取更多示例。

(<a href="#top">返回顶部</a>)

📜 变更

完整的更新日志维护在[GitHub发布页面][Releases]。

(<a href="#top">返回顶部</a>)

🤲 贡献

我们欢迎您的想法、问题和拉取请求。只需遵循常规/标准的GitHub做法即可。

为了便于开发，请使用poetry安装connexion及其所有额外功能，并安装pre-commit钩子以自动运行black格式化和静态分析检查。

    pip install poetry
    poetry install --all-extras
    pre-commit install

通过查看我们的[架构][Architecture]，您可以了解更多关于Connexion如何工作以及在哪里应用您的更改。

除非您事先明确声明，否则您有意提交以包含在本项目中的任何非微不足道的贡献，均应遵守以下所写的Apache License 2.0的条款和条件，不附加任何额外的版权信息、条款或条件。

(<a href="#top">返回顶部</a>)

🙏 致谢

我们要感谢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]

✨ 特性

🫶 赞助商

🪤 为什么选择 Connexion

⚒️ 如何使用

安装

创建您的应用程序

注册API

运行您的应用程序

📜 变更

🤲 贡献

🙏 致谢

📚 推荐资源

编辑推荐精选

Keevx

即梦AI

扣子-AI办公

TRAE编程

蛙蛙写作

问小白

Transly

讯飞智文

讯飞星火

Spark-TTS

探索AI的无限可能

推荐工具精选

TRAE编程

扣子-AI办公

讯飞文书

讯飞绘文

讯飞绘镜

阿里绘蛙

咔片PPT

AI云服务特惠

火山引擎

阿里云

腾讯云

华为云

百度智能云

AWS

关注微信公众号