解析Swagger/OpenAPI 2.0和3.0.0解析器
项目描述
Prance为Python提供了Swagger/OpenAPI 2.0和3.0 API规范的解析器。它使用openapi_spec_validator、swagger_spec_validator或flex来验证规范，但还根据OpenAPI规范解析JSON引用。
后者主要涉及处理非URI引用；OpenAPI可以提供相对文件路径，而JSON引用则需要URI。
使用方法
安装
Prance可在PyPI获得，并且可以通过pip安装。
$ pip install prance请注意，这将安装代码，但还需要指定额外的子包来解锁各种功能。至少需要安装解析后端。对于 CLI 功能，您需要进一步的依赖项。
推荐的安装方式会安装 CLI，使用 ICU 并安装一个验证后端
$ pip install prance[osv,icu,cli]确保在运行上述命令之前已经安装了 ICU Unicode Library 以及 Python 开发库。如果没有，请使用以下命令
$ sudo apt-get install libicu-dev python3-dev # Ubuntu/Debian
$ sudo dnf install libicu-devel python3-devel # Fedora命令行界面
安装 prance 后，将提供 CLI 以验证（并解析规范中的外部引用）
# Validates with resolving
$ prance validate path/to/swagger.yml
# Validates without resolving
$ prance validate --no-resolve path/to/swagger.yml
# Fetch URL, validate and resolve.
$ prance validate http://petstore.swagger.io/v2/swagger.json
Processing "http://petstore.swagger.io/v2/swagger.json"...
-> Resolving external references.
Validates OK as Swagger/OpenAPI 2.0!验证不是 prance 的唯一功能。解析的一个副作用是从包含引用的规范中，可以创建一个完全解析的输出规范。在过去，这通过 validate 命令的选项来完成，但现在有一个专门的命令用于此目的
# Compile spec
$ prance compile path/to/input.yml path/to/output.yml最后，随着 OpenAPI 3.0.0 的到来，工具将旧规范转换为新标准变得很有用。prance 只提供了一个 CLI 命令，用于将规范传递到 swagger2openapi 的网络 API，因此需要网络连接才能使用此命令
# Convert spec
$ prance convert path/to/swagger.yml path/to/openapi.yml代码
您很可能有一个规范文件并希望解析它
from prance import ResolvingParser
parser = ResolvingParser('path/to/my/swagger.yaml')
parser.specification # contains fully resolved specs as a dictPrance 还包括一个不解析 JSON 引用的解析器，以防您更喜欢这种选择。
from prance import BaseParser
parser = BaseParser('path/to/my/swagger.yaml')
parser.specification # contains specs as a dict still containing JSON references在 Windows 上，如果传递 POSIX 类路径（如 /c:/swagger）或相对路径，则代码会正确响应。如果您传递绝对 Windows 路径（如 c:\swagger.yaml），可以使用 prance.util.fs.abspath 将其转换为绝对路径。
也可以解析 URL
parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json')基本上就是这样。还有一整套可能有用也可能不用的实用代码。有关详细信息，请参阅 完整文档。
兼容性
Python 版本
0.16.2 版是最后一个支持 Python 2 的版本。它于 2019 年 11 月 12 日发布。Python 2 于 2019 年年底结束支持。如果您希望更新支持 Python 2 的包，请直接联系维护者。
直到最近，我们还使用 PyPy 进行了测试。不幸的是，Travis 不太擅长支持它。因此，在没有空闲时间的情况下，它们被禁用了。《问题 50》跟踪了这方面的进展。
同样，但不太关键的是，Python 3.4 已不再受到 CI 供应商的很多关注，因此不再支持该版本的自动构建。
后端
不同的验证后端支持不同的功能。
后端 |
Python 版本 |
OpenAPI 版本 |
严格模式 |
备注 |
可用自 |
链接 |
|---|---|---|---|---|---|---|
swagger-spec-validator |
2 和 3 |
仅 2.0 |
是 |
慢；不接受整数键（见严格模式）。 |
prance 0.1 |
|
flex |
2 和 3 |
仅 2.0 |
n/a |
最快；不幸的是已弃用。 |
prance 0.8 |
|
openapi-spec-validator |
2 和 3 |
2.0 和 3.0 |
是 |
慢；不接受整数键（见严格模式）。 |
prance 0.11 |
您可以在解析器（的）构造函数中选择后端
parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json', backend = 'openapi-spec-validator')依赖项中不包含任何后端；它们在运行时检测。如果您安装了它们，就可以使用
$ pip install openapi-spec-validator
$ pip install prance
$ prance validate --backend=openapi-spec-validator path/to/spec.yml关于 flex 使用的说明：虽然 flex 是最快的验证后端，但不幸的是它不再维护，并且其依赖项存在问题。一方面，它依赖于包含安全漏洞的 PyYAML 版本。另一方面，它明确依赖于较旧的 click 版本。
如果您使用flex子包，那么请自行承担风险。
兼容性
有关已知问题列表，请参阅COMPATIBILITY.rst。
部分引用解析
可以指示解析器仅解析某些类型的引用。例如，可以解析来自外部URL的引用，同时保持本地引用（即对本地文件或文件内部的引用）完整。
from prance import ResolvingParser
from prance.util.resolver import RESOLVE_HTTP
parser = ResolvingParser('/path/to/spec', resolve_types = RESOLVE_HTTP)可以通过按位或操作常量来指定多种类型
from prance import ResolvingParser
from prance.util.resolver import RESOLVE_HTTP, RESOLVE_FILES
parser = ResolvingParser('/path/to/spec', resolve_types = RESOLVE_HTTP | RESOLVE_FILES)扩展
Prance包括在Python外部包中引用swagger定义外部的功能。这样的包必须已经可导入（即已安装），并且可以通过ResourceManager API（更多信息这里）访问。
例如，您可能创建一个名为common_swag的包，其中包含文件base.yaml，包含以下定义
definitions:
Severity:
type: string
enum:
- INFO
- WARN
- ERROR
- FATAL在common_swag的setup.py中，您会添加如下行
packages=find_packages('src'),
package_dir={'': 'src'},
package_data={
'': '*.yaml'
}然后，将common_swag安装到某个应用程序中后，现在可以编写以下内容
definitions:
Message:
type: object
properties:
severity:
$ref: 'python://common_swag/base.yaml#/definitions/Severity'
code:
type: string
summary:
type: string
description:
type: string
required:
- severity
- summary贡献
有关详细信息，请参阅CONTRIBUTING.md。
通过finkhaeuser咨询提供专业支持。
许可
基于MIT许可。有关详细信息，请参阅LICENSE.txt文件。
“Prancing unicorn”标志图像版权所有（c）Jens Finkhaeuser。由Moreven B制作。在Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license下允许使用此标志。
下载文件
下载适合您平台文件。如果您不确定选择哪个，请了解有关安装包的更多信息。
