从 openapi 生成 Python 代码

目录

• 如何从 openapi 生成 Python 代码
  • 起因
  • 前置条件
  • 步骤
    • 目标
    • 分析
      • openapi-generator-cli
      • openapi-python-client
      • swagger-codegen-cli.jar
      • datamodel-codegen
    • 其他
    • 总结

如何从 openapi 生成 Python 代码

起因

我在使用 k8s client，但是使用的时候没有类型提示，用起来不是很习惯；所以打算生成类型提示文件

前置条件

• https://tools.openapis.org/categories/code-generators.html

• swagger-codegen

• openapi-python-client

• openapi-generator-cli

  • home

• k8s openapi

• datamodel-codegen

步骤

目标

• 想知道哪个代码生成工具最好用

分析

openapi-generator-cli

两种不同安装方式安装的包，生成的内容是不一样的

k8s python 包应该是用 pip 安装的方式生成的

npm 安装

npm install @openapitools/openapi-generator-cli -g

# download something, the cli can be used when downloading success
openapi-generator-cli

openapi-generator-cli generate -i https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/v3/api__v1_openapi.json -g python -o client

test.py

from client.openapi_client.models import IoK8sApiCoreV1Namespace, IoK8sApiCoreV1NamespaceList

list: IoK8sApiCoreV1NamespaceList = []

# 只有第一级有类型提示
for l1 in list['items'][0].MetaOapg.all_of():
    kind = l1['kind']
    pass

pip 安装

pip install openapi-generator-cli

openapi-generator generate -i https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/v3/api__v1_openapi.json -g python -o client

test2.py

from client.openapi_client.models import IoK8sApiCoreV1Namespace, IoK8sApiCoreV1NamespaceList

list: IoK8sApiCoreV1NamespaceList = []

# 只有第一级有类型提示
for l1 in list.items:
    kind = l1['kind']
    pass

openapi-python-client

安装

pip install openapi-python-client

openapi-python-client generate --url https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/v3/api__v1_openapi.json

cp -r kubernetes-client/kubernetes_client .
rm -rf kubernetes-client

test.py

from kubernetes_client.models import IoK8SApiCoreV1NamespaceList

list: IoK8SApiCoreV1NamespaceList = []

# 有类型提示
for l1 in list.items:
    l1.kind
    pass

swagger-codegen-cli.jar

和pip install openapi-generator-cli生成的结果基本一致

安装

wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.43/swagger-codegen-cli-3.0.43.jar -O swagger-codegen-cli.jar

java -jar swagger-codegen-cli.jar generate -i https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/v3/api__v1_openapi.json -l python -o client

test.py

from client.swagger_client.models import IoK8sApiCoreV1Namespace, IoK8sApiCoreV1NamespaceList

list: IoK8sApiCoreV1NamespaceList = []

# 只有第一级有类型提示
for l1 in list.items:
    kind = l1['kind']
    pass

datamodel-codegen

安装

pip install datamodel-code-generator

datamodel-codegen --target-python-version 3.11 --url https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/v3/api__v1_openapi.json --output client --snake-case-field

test.py

from client.io.k8s.api.core import v1

list: v1.NamespaceList = []

# 有很舒适的提示
for l1 in list.items:
    l1.kind
    pass

其他

由于我们使用的 k8s 只有 swagger2.0 的 spec，因此还需要将 swagger2.0 转换为 openapi3.0

转换工具可以参考 https://www.apimatic.io/dashboard

总结

从上面的测试可以看出，不自定义任何东西，还是openapi-python-client最好用

不过swagger-codegen-cli.jar有自定义 template 生成更好的代码文件的机会，因为他把返回值都写到注释里了

最好用的还是datamodel-codegen。因为我只是想生成类型文件，并不是要生成一个 api-client