pyramid_openapi3

验证Pyramid视图与OpenAPI 3.0/3.1文档

安心无忧

此包存在的目的是在提供RESTful API时让您安心无忧。您无需追逐可预防的错误并向消费者道歉，而是可以专注于生活中更重要的事情。

• 您的API文档永远不会过时，因为它是从您编写的API文档中生成的。
• 文档为您的API中的每个端点提供了试用示例。您不必提供（并维护）curl命令来展示您的API如何工作。用户可以直接在浏览器中尝试。
• 您的API文档始终有效，因为如果文档不符合OpenAPI 3.0规范，您的Pyramid应用程序甚至无法启动。
• 自动请求有效负载验证和清理。您的视图无需任何验证和输入清理的代码。您的视图代码只处理业务逻辑。由于每个请求及其有效负载在到达视图代码之前都经过了API文档的验证，因此无需编写大量测试。
• 您的API的响应始终与API文档相匹配。每个视图的响应都会与文档进行验证，如果响应与文档中所述的某个API端点的输出不完全匹配，则返回500内部服务器错误。这减少了Hyrum's Law的影响。
• 单一事实来源。由于上述检查，您可以确信API文档中所述的内容确实在现实中发生。当询问与API相关的问题时，如“再次提醒我，端点/user/info返回哪些字段？”时，您有一个单一的事实来源可以咨询。
• 基于Pyramid的成熟Python Web框架。Mozilla、Yelp、RollBar和SurveyMonkey等公司信任Pyramid，新的pypi.org也运行在Pyramid上。Pyramid经过彻底的测试和文档，提供灵活性、性能和大量高质量的附加组件。

功能

• 使用openapi-spec-validator验证您的API文档（例如，openapi.yaml或openapi.json）与OpenAPI 3.0规范。
• 为您的API生成并提供服务Swagger试用文档。
• 使用openapi-core验证传入的请求和传出的响应与您的API文档。

入门指南

1. 在Pyramid项目中声明pyramid_openapi3作为依赖项。

2. 包含以下行

   config.include("pyramid_openapi3")
   config.pyramid_openapi3_spec('openapi.yaml', route='/api/v1/openapi.yaml')
   config.pyramid_openapi3_add_explorer(route='/api/v1/')
   

3. 使用openapi 视图谓词启用请求/响应验证

   @view_config(route_name="foobar", openapi=True, renderer='json')
   def myview(request):
       return request.openapi_validated.parameters
   

对于请求，request.openapi_validated可用，包含两个字段：parameters和body。对于响应，如果有效负载与API文档不匹配，则会引发异常。

高级配置

规范中的相对文件引用

OpenAPI3中引入的功能之一是使用$ref链接到外部文件（https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#reference-object）。

使用本功能，您必须确保所有规范文件都位于指定目录中（确保该目录中没有代码，因为目录中的所有文件都作为静态文件公开），然后替换入门中使用的pyramid_openapi3_spec调用，使用以下内容：

config.pyramid_openapi3_spec_directory('path/to/openapi.yaml', route='/api/v1/spec')

一些注意事项

• 不要将pyramid_openapi3_spec_directory的route设置为与pyramid_openapi3_add_explorer的route相同的值。
• 为pyramid_openapi3_spec_directory设置的route不应包含任何文件扩展名，因为这将成为指定filepath中所有文件的根。
• 您不能在同一个应用程序中使用pyramid_openapi3_spec_directory和pyramid_openapi3_spec。

端点/请求/响应验证

pyramid_openapi3提供了一些验证功能

• 传入请求验证（即客户端发送到您的应用程序的内容）
• 传出响应验证（即您的应用程序发送到客户端的内容）
• 端点验证（即您的应用程序注册所有定义的API端点的路由）

这些功能默认启用，但您可以根据需要禁用它们。

config.registry.settings["pyramid_openapi3.enable_endpoint_validation"] = False
config.registry.settings["pyramid_openapi3.enable_request_validation"] = False
config.registry.settings["pyramid_openapi3.enable_response_validation"] = False

[!警告]禁用请求验证将导致request.openapi_validated不可用。

注册Pyramid的路由

您可以在Pyramid应用程序中注册路由。首先，在OpenAPI模式中的PathItem中写入x-pyramid-route-name扩展。

paths:
  /foo:
    x-pyramid-route-name: foo_route
    get:
      responses:
        200:
          description: GET foo

然后，在应用程序的app_factory中放置配置指令pyramid_openapi3_register_routes。

config.pyramid_openapi3_register_routes()

这相当于手动编写以下内容

config.add_route("foo_route", pattern="/foo")

pyramid_openapi3_register_routes()方法支持设置工厂和路由前缀。请参阅源代码以获取详细信息。

指定获取OpenAPI 3规范文件的协议和端口

有时，需要指定协议和端口来访问openapi3规范文件。这可以通过将proto_port可选参数传递给pyramid_openapi3_add_explorer函数来配置。

config.pyramid_openapi3_add_explorer(proto_port=('https', 443))

演示/示例

本软件包提供了三个示例

• 一个相当简单的单文件应用程序，提供Hello World API。
• 一个稍微复杂一些的构建应用程序，提供TODO应用程序API。
• 另一个使用YAML规范分割成多个文件定义的TODO应用程序API。

所有示例都包含测试，以展示pyramid_openapi的错误处理和验证功能。

一个完全构建的应用程序，提供100%的测试覆盖率，提供RealWorld.io API，可在niteoweb/pyramid-realworld-example-app找到。这是一个可在Heroku上部署的Pyramid应用程序，提供类似于Medium.com的社会应用程序的API。鼓励您将其用作下一个项目的脚手架。

设计防御

pyramid_openapi3的作者认为，验证手动编写的API文档的方法优于从Python代码生成API文档的方法。以下是原因

1. 生成和针对文档的验证都是损失过程。运行生成/验证的底层库始终会有所缺失。要么是最新OpenAPI规范中的功能，要么是实现中的错误。不得不为了生成可能仅用于前端的API文档的部分而分叉底层库是不幸的。

   另一方面，验证允许跳过尚不支持的部分的验证，并且不会阻止团队发布文档。

2. 验证方法确实牺牲了DRY原则，必须先编写API文档，然后在Pyramid中编写（视图）代码。一开始感觉有些冗余。然而，这为意图和实现提供了清晰的分离。

3. 生成方法的一个缺点是，即使对于Pyramid后端不处理的部分，也必须编写Python代码，因为这些部分可能由不同的系统处理，或者仅限于文档或API客户端。这会导致Pyramid代码库中出现不应存在的代码。

运行测试

您需要在您的机器上安装poetry和Python 3.10 & 3.12。所有的Makefile命令都假定您已经激活了Poetry环境，即poetry shell。

或者，如果您使用nix，请运行nix-shell进入一个已为开发准备好的shell。

然后您可以运行

make tests

相关包

这些包解决了相同的问题空间

• pyramid_oas3似乎与pyramid_openapi3非常相似，但文档不是英文，我们很遗憾无法仅通过阅读代码就完全理解它的功能。
• pyramid_swagger做的是类似的事情，但针对Swagger 2.0文档。
• connexion采用了与pyramid_openapi3相同的“先编写规范，再编写代码”的方法，但基于Flask。
• bottle-swagger也采用了相同的“先编写规范，再编写代码”的方法，但基于Bottle。
• pyramid_apispec使用apispec和marshmallow验证库进行生成。请参见上面的为什么我们更倾向于验证而不是生成。

弃用策略

我们尽力遵循以下规则。

• 支持Python的最新几个版本，目前为Python 3.10至3.12。
• 支持Pyramid的最新几个版本，目前为1.10.7至2.0.2。
• 支持openapi-core的最新几个版本，目前仅为0.19.0。
• 请参阅poetry.lock以获取所有依赖项的已知良好集。

野外使用

一些在生产中使用pyramid_openapi3的项目

• Pareto Security Team Dashboard API - Pareto Security macOS安全应用的团队仪表板。
• SEO Domain Finder API - 用于查找具有SEO价值的过期域的工具。
• Rankalyzer.io - 监控竞争对手的SEO变化和策略，以改善您的搜索流量。
• Kafkai API - Kafkai文本生成服务的用户控制面板。
• Open on-chain data API - 去中心化交易所和区块链交易数据开放API。
• Mayet RX - 药品/医疗临床试验的供应商管理系统。