OpenApi自动生成client.md

邓俊材
2023-12-01

前言

之前没有觉得OpenApi有什么特别了不得的,直到参加了花旗银行的一次面试,对方部门老总对OpenApi是非常重视,认为可以极大提升效率;后来在eBay,随着微服务化的推行,应用之间RESTful调用指数级增长,应用内调用接口的代码占了很大一部分,复用程度不高,比如一个基础应用A被10个上层应用调用,各写各的后果如下:

  • 10个应用有的用okHttp有的用apache http,不统一
  • 单元测试覆盖率要达到80%,意味着相同功能加10倍UT
  • 缺乏重试、异常处理等机制

后来试用了OpenApi,将如上10个应用的代码,代替为OpenApi生成的jar包(jar包可以统一管理,10个应用引入即可),采用的技术统一,UT只要一份,代码质量有保证!


OpenApi和swagger

OpenApi解析swagger的接口的规程,自动生成java类库,非常方便!

网易链接口调用关系.md 里面用到了自己编写的okHttpClient,但是如果能够自动生成,岂不是很方便?
swagger.md 原理是利用swagger.json,里面有详细的返回的类及哪些接口

20190924: 跑通了整体流程,最大改动:submitTime原来是offsetTime类型的,后来我改为string还是不过,后来干脆取消对这个字段的读取,就通过了;另外发现一个jobType的问题,是haowen在qm上遗漏了,已经fix了


具体操作 hands-on

  1. 先把swagger.json 下载下来
  2. 在运行
$ java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -i workswagger.json -g java -o /var/tmp/javaClient4Workflow

上传到ebay的qa库中,小窍门是1.0-SNAPSHOT,否则报错

[INFO] --- maven-deploy-plugin:2.7:deploy (default-deploy) @ openapi-workflow-client ---
Downloading: https://ebaycentral.qa.ebay.com/content/repositories/snapshots/com/ebay/marketing/opclients/openapi-workflow-client/1.0-SNAPSHOT/maven-metadata.xml
Uploading: https://ebaycentral.qa.ebay.com/content/repositories/snapshots/com/ebay/marketing/opclients/openapi-workflow-client/1.0-SNAPSHOT/openapi-workflow-client-1.0-20190918.062345-1.jar
Uploaded: https://ebaycentral.qa.ebay.com/content/repositories/snapshots/com/ebay/marketing/opclients/openapi-workflow-client/1.0-SNAPSHOT/openapi-workflow-client-1.0-20190918.062345-1.jar (102 KB at 45.3 KB/sec)
Uploading: https://ebaycentral.qa.ebay.com/content/repositories/snapshots/com/ebay/marketing/opclients/openapi-workflow-client/1.0-SNAPSHOT/openapi-workflow-client-1.0-20190918.062345-1.pom
Uploaded: https://ebaycentral.qa.ebay.com/content/repositories/snapshots/com/ebay/marketing/opclients/openapi-workflow-client/1.0-SNAPSHOT/openapi-workflow-client-1.0-20190918.062345-1.pom (11 KB at 15.3 KB/sec)


平常做spring-boot项目在服务间相互调用时一般都是RestTemplate,有了这个就不用了,可以生成client端的jar包,直接调用jar包中的方法就会进行服务调用

命令

git clone https://github.com/openapitools/openapi-generator.git
cd openapi-generator
mvn clean install
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
  -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
  -l jaxrs-cxf-client \
  -o /var/tmp/openapi-generator/jaxrs-cxf-client

openapi-generator-cli help
用list命令尝试

config-help

meta

validate (先验证一下给的petstore的例子)

openapi-generator validate -i petstore-v3.0.yaml
$ java -jar openapi-generator-cli.jar help
usage: openapi-generator-cli <command> [<args>]

The most commonly used openapi-generator-cli commands are:
    config-help Config help for chosen lang
    generate Generate code with the specified generator.
    help Display help information
    list Lists the available generators
    meta MetaGenerator. Generator for creating a new template set and configuration for Codegen. The output will be based on the language you specify, and includes default templates to include.
    validate Validate specification
    version Show version information
 类似资料: