从 OpenAPI 生成现代 Python 客户端
项目描述
openapi-python-客户端
从 OpenAPI 3.x 文档生成现代 Python 客户端。
此生成器不支持 OpenAPI 2.x FKA Swagger。如果您需要使用较旧的文档，请先尝试使用许多可用转换器之一将其升级到版本 3。
此项目仍在开发中，不支持所有 OpenAPI 功能
为什么这个？
该工具专注于通过以下方式为 Python 开发人员创造最佳的开发人员体验：
- 使用所有最新最好的 Python 特性，如类型注释和数据类。
- 具有特定于该生成器的文档和使用说明。
- 使用 Jinja2 模板用 Python 编写，使 Python 开发人员更容易改进和扩展。如果您已经拥有 Python，安装和使用它也容易得多。
安装
我建议您使用pipx安装，这样您就不会与您可能拥有的任何其他软件包冲突：pipx install openapi-python-client --include-deps.
请注意该
--include-deps选项也将使black,isort和autoflake在您的路径中可用，以便openapi-python-client可以使用它们来清理生成的代码。
如果您使用pipx run，那么除非您手动安装，否则后生成挂钩将不可用。
您也可以使用普通 pip 安装：pip install openapi-python-client
然后，如果你想要制表符完成：openapi-python-client --install-completion
用法
创建一个新客户端
openapi-python-client generate --url https://my.api.com/openapi.json
这将根据您的 OpenAPI 规范中的标题生成一个新的客户端库。例如，如果您的 API 的标题是“我的 API”，那么预期的输出将是“my-api-client”。如果该名称的文件夹已存在，您将收到错误消息。
如果您openapi.json在磁盘上有可用文件，则在任何 CLI 调用中，您都可以通过替换--url为--path：
openapi-python-client generate --path location/on/disk/openapi.json
更新现有客户端
openapi-python-client update --url https://my.api.com/openapi.json
有关更多使用详情，请运行
openapi-python-client --help或阅读使用情况
使用自定义模板
此功能利用 Jinja2 的ChoiceLoader和FileSystemLoader。这意味着您不需要自定义每个模板。只需将要自定义的模板从默认模板目录复制到您自己的自定义模板目录（文件名必须完全匹配），然后通过custom-template-path标志将模板目录传递给generateandupdate命令。例如，
openapi-python-client update \
--url https://my.api.com/openapi.json \
--custom-template-path=relative/path/to/mytemplates
请注意，这是一个 beta 级功能，因为模板中公开的 API 未记录且不稳定。
你得到什么
- 带有一些基本元数据的
pyproject.toml文件，旨在与Poetry一起使用。 - A
README.md您肯定需要更新项目的详细信息 - 一个 Python 模块，其名称与自动生成的项目名称（例如“my_api_client”）类似，其中包含：
- 一个
client同时具有Client类和AuthenticatedClient类的模块。您将需要这些来调用api模块中的函数。 - 一个
api模块，它将为您的 OpenAPI 规范中的每个标签包含一个模块，以及一个default用于没有标签的端点的模块。这些模块中的每一个又包含一个用于调用每个端点的函数。 models具有 OpenAPI 规范中各种模式定义的所有类的模块
- 一个
有关完整示例，您可以查看end_to_end_tests包含openapi.json文件的目录。同一目录中的“golden-record”是从该 OpenAPI 文档生成的客户端。
支持的 OpenAPI 功能
- 所有 HTTP 方法
- JSON 和表单主体、路径和查询参数
- 带有多部分/表单数据主体的文件上传
- 浮点数、字符串、整数、日期、日期时间、字符串枚举，以及包含任何这些的自定义模式或列表
- 包含上述任何类型的 html/text 或 application/json 响应
- 不记名令牌安全
配置
您可以使用选项将 YAML（或 JSON）文件传递给 openapi-python-client--config以更改某些行为。支持以下参数：
类覆盖
用于更改生成的模型类的名称。此参数应该是现有类名（通常是 OpenAPI 文档的“模式”部分中的键）到 class_name 和 module_name 的映射。例如，如果 OpenAPI 中的模型名称（因此生成的类名称）类似于“_PrivateInternalLongName”，并且您希望生成的客户端模型在名为“short_name”的模块中称为“ShortName”，您可以这样做这个：
例子：
class_overrides:
_PrivateInternalLongName:
class_name: ShortName
module_name: short_name
找到需要覆盖的最简单的方法可能是生成您的客户端并查看模型文件夹中的所有内容。
project_name_override 和 package_name_override
用于更改生成的客户端库项目/包的名称。如果项目名称已更改但未提供包名称的覆盖，则包名称将使用标准约定从项目名称转换（将-'s替换为_'s）。
例子：
project_name_override: my-special-project-name
package_name_override: my_extra_special_package_name
字段前缀
生成属性时，name将使用 OpenAPI 模式的属性。当name不是有效的 Python 标识符（例如以数字开头）时，该字符串将被添加。默认为“field_”。
例子：
field_prefix: attr_
package_version_override
指定生成的客户端的包版本。如果未设置，客户端将使用 OpenAPI 规范的版本。
例子：
package_version_override: 1.2.3
post_hooks
在配置文件中，有一种简单的方法可以告诉openapi-python-client您在生成后运行其他命令。这是一个示例，显示了如果您不在配置中覆盖它们将运行的默认命令：
post_hooks:
- "autoflake -i -r --remove-all-unused-imports --remove-unused-variables --ignore-init-module-imports ."
- "isort ."
- "black ."
