Spring Boot中使用Swagger CodeGen生成REST client
Swagger是一個非常好用的API工具，我們會使用Swagger來暴露API給外界測試，那么有沒有簡單的辦法來生成對應的調client呢？
Swagger CodeGen是一個REST 客戶端生成工具，它可以從Open API的規范定義文件中生成對應的REST Client代碼。本文我們將會舉例說明如何通過OpenAPI 規范定義文件自動生成REST Client。
什么是Open API規范定義文件呢？
OpenAPI規范（OAS）為RESTful API定義了一個與語言無關的標准接口，使人類和計算機都可以發現和理解服務的功能，而無需訪問源代碼，文檔或通過網絡流量檢查。 正確定義后，使用者可以使用最少的實現邏輯來理解遠程服務並與之交互。
然后，文檔生成工具可以使用OpenAPI定義來顯示API，代碼生成工具可以使用各種編程語言，測試工具和許多其他用例來生成服務器和客戶端。
值得一提的是OpenAPI規范最早也是Swagger提出來的，后面被捐贈給了社區。
推薦的OpenAPI 文檔名字通常為openapi.json 或者 openapi.yaml。
我們看一個swagger自帶的 petstore open api 例子： https://petstore.swagger.io/v2/swagger.json
{
"swagger": "2.0",
"info": {
"description": "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.",
"version": "1.0.3",
"title": "Swagger Petstore",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"email": "apiteam@swagger.io"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"host": "petstore.swagger.io",
"basePath": "/v2",
"tags": [
...
],
"schemes": [
"https",
"http"
],
"paths": {
...
"definitions": {
...
},
"externalDocs": {
"description": "Find out more about Swagger",
"url": "http://swagger.io"
}
}
我們可以看到在這個open API 定義文件里面包含了我們在swagger界面上看到的一切，paths，definitions等。
生成Rest Client
有了Open Api定義文件之后，我們就可以使用 swagger-codegen-cli 來生成對應的rest client文件了。
目前為止，最新的swagger-codegen-cli版本是2.4.12， 我們可以從這里下載 https://search.maven.org/classic/remotecontent?filepath=io/swagger/swagger-codegen-cli/2.4.12/swagger-codegen-cli-2.4.12.jar。
下載到本地之后，我們可以通過如下命令來生成rest client：
java -jar swagger-codegen-cli-2.4.12.jar generate \
-i http://petstore.swagger.io/v2/swagger.json \
--api-package com.flydean.client.api \
--model-package com.flydean.client.model \
--invoker-package com.flydean.client.invoker \
--group-id com.flydean \
--artifact-id springboot-generate-restclient \
--artifact-version 0.0.1-SNAPSHOT \
-l java \
--library resttemplate \
-o springboot-generate-restclient
上述的參數包含：
- -i 指定了open api 定義文件的地址
- –api-package, –model-package, –invoker-package 指定了生成文件的package
- –group-id, –artifact-id, –artifact-version 指定生成的maven 項目的屬性
- -l 指明生成的代碼編程語言
- –library 指定了實際的實現框架
- -o 指定輸出文件目錄
Swagger Codegen 支持如下的Java 庫：
- jersey1 – Jersey1 + Jackson
- jersey2 – Jersey2 + Jackson
- feign – OpenFeign + Jackson
- okhttp-gson – OkHttp + Gson
- retrofit (Obsolete) – Retrofit1/OkHttp + Gson
- retrofit2 – Retrofit2/OkHttp + Gson
- rest-template – Spring RestTemplate + Jackson
- rest-easy – Resteasy + Jackson
在Spring Boot中使用
我們把生成的代碼拷貝到我們的Spring Boot項目中。然后通過下面的代碼來啟動應用程序:
@SpringBootApplication
public class GenerateClientApp {
public static void main(String[] args) {
SpringApplication.run(GenerateClientApp.class, args);
}
@Bean
public RestTemplate restTemplate(RestTemplateBuilder builder) {
return builder.build();
}
}
我們再定義一個controller：
@RestController
public class PetController {
@Autowired
private PetApi petApi;
@GetMapping("/api/findAvailablePets")
public List<Pet> findAvailablePets() {
return petApi.findPetsByStatus(Arrays.asList("available"));
}
}
現在通過curl localhost:8080/api/findAvailablePets就可以遠程調用http://petstore.swagger.io/v2/swagger.json 里面暴露的接口了。
API Client 配置
默認情況下ApiClient是默認的不需要認證的，如果需要認證，可以自定義ApiClient如下：
@Bean
public ApiClient apiClient() {
ApiClient apiClient = new ApiClient();
OAuth petStoreAuth = (OAuth) apiClient.getAuthentication("petstore_auth");
petStoreAuth.setAccessToken("special-key");
return apiClient;
}
使用Maven plugin
除了使用cli命令之外，我們還可以在pom中添加plugin來實現這個功能：
<build>
<plugins>
<plugin>
<groupId>io.swagger</groupId>
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>2.4.12</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>swagger.json</inputSpec>
<language>java</language>
<library>resttemplate</library>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
在線生成API
我們可以通過http://generator.swagger.io來在線生成API代碼：
curl -X POST -H "content-type:application/json" \
-d '{"swaggerUrl":"http://petstore.swagger.io/v2/swagger.json"}' \
http://generator.swagger.io/api/gen/clients/java
該命令會返回一個包含代碼的zip包供你下載。
本文的例子可以參考 https://github.com/ddean2009/learn-springboot2/tree/master/springboot-generate-restclient
更多教程請參考 flydean的博客