文章目錄

• • 什么是Open API規(guī)范定義文件呢？
  • 生成Rest Client
  • 在Spring Boot中使用
  • API Client 配置
  • 使用Maven plugin
  • 在線生成API

Spring Boot中使用Swagger CodeGen生成REST client

Swagger是一個非常好用的API工具，我們會使用Swagger來暴露API給外界測試，那么有沒有簡單的辦法來生成對應(yīng)的調(diào)client呢？

Swagger CodeGen是一個REST 客戶端生成工具，它可以從Open API的規(guī)范定義文件中生成對應(yīng)的REST Client代碼。本文我們將會舉例說明如何通過OpenAPI 規(guī)范定義文件自動生成REST Client。

什么是Open API規(guī)范定義文件呢？

OpenAPI規(guī)范（OAS）為RESTful API定義了一個與語言無關(guān)的標(biāo)準(zhǔn)接口，使人類和計算機(jī)都可以發(fā)現(xiàn)和理解服務(wù)的功能，而無需訪問源代碼，文檔或通過網(wǎng)絡(luò)流量檢查。 正確定義后，使用者可以使用最少的實現(xiàn)邏輯來理解遠(yuǎn)程服務(wù)并與之交互。

然后，文檔生成工具可以使用OpenAPI定義來顯示API，代碼生成工具可以使用各種編程語言，測試工具和許多其他用例來生成服務(wù)器和客戶端。

值得一提的是OpenAPI規(guī)范最早也是Swagger提出來的，后面被捐贈給了社區(qū)。

推薦的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 來生成對應(yīng)的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

上述的參數(shù)包含：

• -i 指定了open api 定義文件的地址
• –api-package, –model-package, –invoker-package 指定了生成文件的package
• –group-id, –artifact-id, –artifact-version 指定生成的maven 項目的屬性
• -l 指明生成的代碼編程語言
• –library 指定了實際的實現(xiàn)框架
• -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項目中。然后通過下面的代碼來啟動應(yīng)用程序:

@SpringBootApplication public class GenerateClientApp {public static void main(String[] args) {SpringApplication.run(GenerateClientApp.class, args);}@Beanpublic RestTemplate restTemplate(RestTemplateBuilder builder) {return builder.build();}}

我們再定義一個controller：

@RestController public class PetController {@Autowiredprivate PetApi petApi;@GetMapping("/api/findAvailablePets")public List<Pet> findAvailablePets() {return petApi.findPetsByStatus(Arrays.asList("available"));} }

現(xiàn)在通過curl localhost:8080/api/findAvailablePets就可以遠(yuǎn)程調(diào)用http://petstore.swagger.io/v2/swagger.json 里面暴露的接口了。

API Client 配置

默認(rèn)情況下ApiClient是默認(rèn)的不需要認(rèn)證的，如果需要認(rèn)證，可以自定義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來實現(xiàn)這個功能：

<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

更多精彩內(nèi)容且看：

• 區(qū)塊鏈從入門到放棄系列教程-涵蓋密碼學(xué),超級賬本,以太坊,Libra,比特幣等持續(xù)更新
• Spring Boot 2.X系列教程:七天從無到有掌握Spring Boot-持續(xù)更新
• Spring 5.X系列教程:滿足你對Spring5的一切想象-持續(xù)更新
• java程序員從小工到專家成神之路（2020版）-持續(xù)更新中,附詳細(xì)文章教程

更多教程請參考 flydean的博客

總結(jié)

以上是生活随笔為你收集整理的Spring Boot中使用Swagger CodeGen生成REST client的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。