openapi-generator教程

一、簡介

Github地址：https://github.com/OpenAPITools/openapi-generator

官網文檔： https://openapi-generator.tech/docs/installation

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

在Github上，openapi-generator項目擁有Star 10k，Contributors 近2000，是一個非常優秀的項目，支持多種安裝方式，以及支持通過yaml、JSON文件生成幾十種客戶端和服務端語言，生成的SDK代碼十分優雅，代碼中也包含了注釋，非常容易閱讀。同時，還生成了非常詳細的markdown文檔。

二、安裝

openapi-generator支持多種安裝方式：npm、Homebrew、Docker、JAR、Bash Launcher Script

詳細的安裝文檔地址：https://openapi-generator.tech/docs/installation

下面以npm安裝方式簡要說明一下

npm支持的平台有Linux、macOS、Windows，需要本機已經安裝了node.js

使用npm安裝openapi-generator非常簡單，就三行命令

# 安裝腳手架
npm install @openapitools/openapi-generator-cli -g
# 設置使用的版本
openapi-generator-cli version-manager set 5.1.0
# 添加依賴
npm install @openapitools/openapi-generator-cli -D

 

三、使用

下面以官方提供的yaml文件生成一個java sdk做示例

https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml 

# 官方提供openapi-generator命令格式如下
npx @openapitools/openapi-generator-cli generate -i petstore.yaml -g ruby -o /tmp/test/
# -i petstore.yaml 表示要根據哪個文檔生成，支持yaml和json
# -g ruby          表示生成ruby client
# -o /tmp/test/    指定存放的地址

所以，根據我們下載下來的petstore.yaml，我們生成一個java項目

npx @openapitools/openapi-generator-cli generate -i petstore.yaml -g java -o G:\openapi-generator\sdk

 

 通過IDEA打開生成的項目，成功編譯通過以及運行成功，項目提供了優雅的代碼以及單元測試，同時還提供了markdown文檔告訴你怎么編譯項目、如何使用sdk以及api接口文檔，功能十分強大

 

  

四、支持語言

在官方文檔中，支持了幾乎常見的所有語言，你所知道的java、csharp、csharp-netcore、python、go、c、c++、php等等都能支持，詳細文檔如下：https://openapi-generator.tech/docs/generators 

五、建議

從上面教程，我們可以使用yaml或者json文件以標准的格式生成多語言sdk，一般而言，我們在開發api接口的時候，最好引入swagger中間件，並且在編寫代碼的時候加入接口描述，這樣生成的swagger.json也包含了api的描述信息，我們通過swagger.json直接生成多語言sdk，直接省去了我們編寫sdk，通過一行命令就直接生成想要的語言，節省100%的工作，而且通過openapi-generator還幫我們寫好了markdown文檔，簡直不要太舒服。