我正在學習 Swagger 以及如何使用 Swagger codegen 生成 REST 客戶端。我知道如何用 Swagger 做文檔，我也知道如何用 Swagger 生成一個簡單的 REST 服務(wù)器，但我不知道如何用 Swagger codegen 生成一個簡單的 REST 客戶端。例如，我有一個簡單的應(yīng)用程序，它是一個 REST 服務(wù)器，我想生成 REST 客戶端。我可以用 Swagger codegen 做到這一點嗎？REST 服務(wù)器的控制器：package com.dgs.spring.springbootswagger.controller;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import io.swagger.annotations.ApiResponse;import io.swagger.annotations.ApiResponses;@RestController@RequestMapping("/api/v1")@Api(value = "Employee Management System", description = "Operations pertaining to employee in Employee Management System")public class EmployeeController { @Autowired private EmployeeRepository employeeRepository; @ApiOperation(value = "View a list of available employees", response = List.class) @ApiResponses(value = { @ApiResponse(code = 200, message = "Successfully retrieved list"), @ApiResponse(code = 401, message = "You are not authorized to view the resource"), @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"), @ApiResponse(code = 404, message = "The resource you were trying to reach is not found") }) @GetMapping("/employees") public List<Employee> getAllEmployees() { return employeeRepository.findAll(); } @ApiOperation(value = "Get an employee by Id") @GetMapping("/employees/{id}") public ResponseEntity<Employee> getEmployeeById( @ApiParam(value = "Employee id from which employee object will retrieve", required = true) @PathVariable(value = "id") Long employeeId) throws ResourceNotFoundException { Employee employee = employeeRepository.findById(employeeId) .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId)); return ResponseEntity.ok().body(employee); }}
5 回答
函數(shù)式編程
TA貢獻1807條經(jīng)驗 獲得超9個贊
是的。您可以使用它swagger-codegen-maven-plugin來生成 REST 客戶端。但在此之前，您需要在 YAML 或 JSON 中描述 REST API，主要是OpenAPI Specification?因為swagger-codegen-maven-plugin只能從本規(guī)范中編寫的文件生成 REST 客戶端。
其他答案假定您需要手動編寫規(guī)范，而我的解決方案更進一步，可以從 REST 控制器源代碼自動生成規(guī)范。
最新的 OpenAPI 版本是 3.0 。但是根據(jù)您導入的 swagger 注釋的包，您使用的是 2.0（或之前）版本。所以我的解決方案假設(shè)您使用的是 OpenAPI 2.0。
生成開放 API 規(guī)范
首先，您可以使用swagger-maven-plugin從 RestController 源代碼生成 OpenAPI 規(guī)范。@RestController它基本上分析在指定的類中注釋的 Swagger 注釋<locations>，并將 OpenAPI 規(guī)范轉(zhuǎn)儲到/src/main/resources/swagger.json：
<plugin>
? ? <groupId>com.github.kongchen</groupId>
? ? <artifactId>swagger-maven-plugin</artifactId>
? ? <version>3.1.5</version>
? ? <configuration>
? ? ? ? <apiSources>
? ? ? ? ? ? <apiSource>
? ? ? ? ? ? ? ? <springmvc>true</springmvc>
? ? ? ? ? ? ? ? <locations>
? ? ? ? ? ? ? ? ? ? <location>com.dgs.spring.springbootswagger.controller.EmployeeController</location>
? ? ? ? ? ? ? ? ? ? <location>com.dgs.spring.springbootswagger.controller.FooController</location>
? ? ? ? ? ? ? ? </locations>
? ? ? ? ? ? ? ? <schemes>
? ? ? ? ? ? ? ? ? ? <scheme>http</scheme>
? ? ? ? ? ? ? ? </schemes>
? ? ? ? ? ? ? ? <host>127.0.0.1:8080</host>
? ? ? ? ? ? ? ? <basePath>/</basePath>
? ? ? ? ? ? ? ? <info>
? ? ? ? ? ? ? ? ? ? <title>My API</title>
? ? ? ? ? ? ? ? ? ? <version>1.1.1</version>
? ? ? ? ? ? ? ? </info>
? ? ? ? ? ? ? ? <swaggerDirectory>${basedir}/src/main/resources/</swaggerDirectory>
? ? ? ? ? ? </apiSource>
? ? ? ? </apiSources>
? ? </configuration>
? ? <executions>
? ? ? ? <execution>
? ? ? ? ? ? <goals>
? ? ? ? ? ? ? ? <goal>generate</goal>
? ? ? ? ? ? </goals>
? ? ? ? </execution>
? ? </executions>
</plugin>
執(zhí)行以下maven命令開始生成：
mvn clean compile
生成 Rest 客戶端
生成后swagger.json，您可以將其復制并粘貼到您的客戶端項目（例如/src/main/resources/swagger.json）。然后我們可以使用它swagger-codegen-maven-plugin來生成一個 HTTP 客戶端。
默認情況下，它將生成整個 Maven 項目，其中包括測試用例和其他文檔資料。但我想要的只是 HttpClient 的源代碼，沒有其他東西。經(jīng)過多次嘗試和錯誤，我確定了以下配置：
<plugin>
? ? <groupId>io.swagger</groupId>
? ? <artifactId>swagger-codegen-maven-plugin</artifactId>
? ? <version>2.4.7</version>
? ? <executions>
? ? ? ? <execution>
? ? ? ? ? ? <goals>
? ? ? ? ? ? ? ? <goal>generate</goal>
? ? ? ? ? ? </goals>
? ? ? ? ? ? <configuration>
? ? ? ? ? ? ? ? <inputSpec>${basedir}/src/main/resources/swagger.json</inputSpec>
? ? ? ? ? ? ? ? <language>java</language>
? ? ? ? ? ? ? ? <library>resttemplate</library>
? ? ? ? ? ? ? ? <output>${project.basedir}/target/generated-sources/</output>
? ? ? ? ? ? ? ? <apiPackage>com.example.demo.restclient.api</apiPackage>
? ? ? ? ? ? ? ? <modelPackage>com.example.demo.restclient.model</modelPackage>
? ? ? ? ? ? ? ? <invokerPackage>com.example.demo.restclient</invokerPackage>
? ? ? ? ? ? ? ? <generateApiTests>false</generateApiTests>
? ? ? ? ? ? ? ? <generateModelTests>false</generateModelTests>
? ? ? ? ? ? ? ? <generateApiDocumentation>false</generateApiDocumentation>
? ? ? ? ? ? ? ? <generateModelDocumentation>false</generateModelDocumentation>
? ? ? ? ? ? ? ? <configOptions>
? ? ? ? ? ? ? ? ? ? <dateLibrary>java8</dateLibrary>
? ? ? ? ? ? ? ? ? ? <sourceFolder>restclient</sourceFolder>
? ? ? ? ? ? ? ? </configOptions>
? ? ? ? ? ? </configuration>
? ? ? ? </execution>
? ? </executions>
</plugin>
生成的HTTP客戶端是基于RestTemplate的，會生成到文件夾中target/generated-sources/restclient。您可能必須配置 IDE 以導入生成的客戶端才能使用它。（如果是Eclipse，可以在Project Properties中配置??Java Build Path ??添加生成的rest client的文件夾）
要開始生成客戶端，只需執(zhí)行 maven 命令：
mvn clean compile
要使用生成的 HTTP 客戶端：
ApiClient apiClient = new ApiClient();
//Override the default API base path configured in Maven
apiClient.setBasePath("http://api.example.com/api");
EmployeeManagementSystemApi api = new EmployeeManagementSystemApi(apiClient);
api.getEmployeeById(1l);
qq_笑_17
TA貢獻1818條經(jīng)驗 獲得超7個贊
僅供參考，一種使用命令行的簡單方法：
例如執(zhí)行命令：
java?-jar?swagger-codegen-cli.jar?generate?\ ??-i?http://mydomain/v2/swagger.json?\ ??--api-package?com.mypackage.api?\ ??--model-package?com.mypackage.model?\ ??--invoker-package?com.mypackage.invoker?\ ??--group-id?com.mygroup?\ ??--artifact-id?spring-swagger-codegen-api-client?\ ??--artifact-version?0.0.1-SNAPSHOT?\ ??-l?java?\ ??--library?resttemplate?\ ??-o?spring-swagger-codegen-api-client
Swagger Codegen 支持以下客戶端實現(xiàn)：
球衣1 +杰克遜
Jersey2 + 杰克遜
假裝+杰克遜
OkHttp + Gson
Retrofit2/OkHttp + Gson
Spring RestTemplate + Jackson
Resteasy + 杰克遜
PS 如您所見，其余客戶端是從 swagger 規(guī)范定義生成的，并使用“-i”參數(shù)定義。
夢里花落0921
TA貢獻1772條經(jīng)驗 獲得超6個贊
招搖端點
假設(shè)您的應(yīng)用程序的 Swagger 端點可以在以下位置訪問：
測試 Swagger 2.0 JSON API 文檔
http://localhost:8080/v2/api-docs?group=employee
http://localhost:8080/v2/api-docs（如果你還沒有設(shè)置一個名為的組
employee）測試 Swagger 用戶界面
下載 Swagger Codegen 可執(zhí)行文件
您可以從 Maven 中央存儲庫下載swagger-codegen-cli-2.4.7.jar 。
生成客戶端代碼
現(xiàn)在您已經(jīng)有了 Swagger Codegen JAR，您可以通過執(zhí)行以下命令來生成 REST 客戶端：
java?-jar?swagger-codegen-cli-2.4.7.jar?generate?\ ??-i?http://localhost:8080/v2/api-docs?group=employee?\ ??-l?java?\ ??-o?swagger-codegen-client
如果沒有大搖大擺的分組，
java?-jar?swagger-codegen-cli-2.4.7.jar?generate?\ ??-i?http://localhost:8080/v2/api-docs?\ ??-l?java?\ ??-o?swagger-codegen-client
選項
盡管 Swagger Codegen CLI 附帶了許多選項，但我們使用的是生成客戶端代碼絕對必要的選項。
-i指向您的應(yīng)用程序的 URL?Swagger api docs。-l客戶端的編程語言，在這種情況下是java-o生成的客戶端代碼的輸出文件夾。
執(zhí)行前面生成代碼的命令后，您應(yīng)該注意到終端上出現(xiàn)以下消息：
[main] INFO io.swagger.parser.Swagger20Parser - reading from http://localhost:8080/v2/api-docs?group=employee
[main] WARN io.swagger.codegen.ignore.CodegenIgnoreProcessor - Output directory does not exist, or is inaccessible. No file (.swagger-codegen-ignore) will be evaluated.
[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/src/main/java/io/swagger/client/model/Employee.java
[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/docs/Employee.md
[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/src/main/java/io/swagger/client/api/EmployeeControllerApi.java
...
[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/src/main/java/io/swagger/client/ApiClient.java
...
REST 客戶端項目
代碼生成完成后，您應(yīng)該注意到一個gradle/maven具有以下結(jié)構(gòu)的項目：
__ swagger-codegen-client
? |__ README.md
? |__ build.gradle
? |__ build.sbt
? |__ docs
? |__ git_push.sh
? |__ gradle
? |__ gradle.properties
? |__ gradlew
? |__ gradlew.bat
? |__ pom.xml
? |__ settings.gradle
? |__ src
? ? ?|__ main
? ? ? ? |__ java
? ? ? ? ? |__ io.swagger.client.api
? ? ? ? ? ? ?|__ EmployeeControllerApi.java
? ? ?|__ test
? ? ? ? |__ java
? ? ? ? ? |__ io.swagger.client.api
? ? ? ? ? ? ?|__ EmployeeControllerApiTest.java
可以在此處找到生成的客戶端項目的示例。
使用 REST 客戶端
客戶端項目包含很多 java 類。然而，最重要的類是EmployeeControllerApi.java。這是包含用于制作 REST 客戶端類的所有邏輯的類。
另一個重要的類是EmployeeControllerApiTest.java。它向您展示了如何使用EmployeeControllerApi.java。生成的客戶端項目還提供了一個非常有用的README文件。
網(wǎng)址更改
ApiClient類包含與建立 HTTP 客戶端連接相關(guān)的信息。請確保basePath?您的 REST 應(yīng)用程序正確無誤。在生成的示例中，basePath有一個https://localhost:8080URL 而不是http://localhost:8080.
Java 12 的變化
生成的項目適用于 Java 8。如果您使用的是 Java 12，則必須添加以下依賴項才能使項目編譯：
? ? <dependency>
? ? ? ? <groupId>javax.xml.bind</groupId>
? ? ? ? <artifactId>jaxb-api</artifactId>
? ? ? ? <version>2.3.0</version>
? ? </dependency>
? ? <dependency>
? ? ? ? <groupId>com.sun.xml.bind</groupId>
? ? ? ? <artifactId>jaxb-core</artifactId>
? ? ? ? <version>2.3.0</version>
? ? </dependency>
? ? <dependency>
? ? ? ? <groupId>com.sun.xml.bind</groupId>
? ? ? ? <artifactId>jaxb-impl</artifactId>
? ? ? ? <version>2.3.0</version>
? ? </dependency>
? ? <dependency>
? ? ? ? <groupId>javax.annotation</groupId>
? ? ? ? <artifactId>javax.annotation-api</artifactId>
? ? ? ? <version>1.3.2</version>
? ? </dependency>
示例 REST 調(diào)用
employee下面是通過調(diào)用 REST POST 方法方法來創(chuàng)建的示例。
Employee employee = new Employee();
employee.setId(3L);
employee.setFirstName("Sam");
employee.setLastName("Fox");
employee.setEmail("sfox@gmail.com");
EmployeeControllerApi api = new EmployeeControllerApi();
Employee response = api.createEmployeeUsingPOST(employee);
System.out.println(response);
你應(yīng)該得到類似這樣的回應(yīng)：
class Employee {
? ? email: sfox@gmail.com
? ? firstName: Sam
? ? id: 3
? ? lastName: Fox
}
MMMHUHU
TA貢獻1834條經(jīng)驗 獲得超8個贊
1) 轉(zhuǎn)到https://editor.swagger.io創(chuàng)建你的 swagger 文檔，我以“Swagger Petstore”為例
2) 現(xiàn)在選擇文件，導入文件并上傳下載的 swagger.json 文件
3) 打開https://swagger.io/tools/swagger-codegen/
4）使用以下步驟：
i) 將存儲庫克隆到磁盤 git clone?https://github.com/swagger-api/swagger-codegen.git
ii) 運行 mvn clean package
iii) 將 swagger-codegen-cli.jar 文件從目標文件夾復制到計算機上的本地驅(qū)動器。
iv) 接下來執(zhí)行以下命令生成客戶端：
?????java?-jar?swagger-codegen-cli.jar?-i?<json_file>?-l?python?-o?my_client
此命令有三個參數(shù)：
?-i?Specifies?the?path?to?the?input?file.?This?can?be?a?URL ?-l?Specifies?the?programming?language?for?the?client ?-o?Specifies?the?output?directory?where?the?generate?code?should?be?located
Swagger Codegen 是一個開源項目，它允許從 OpenAPI 規(guī)范自動生成 API 客戶端庫（SDK 生成）、服務(wù)器存根和文檔。Swagger Codegen 可在 GitHub 存儲庫中下載，也可在集成的 SwaggerHub 平臺中為任何新的或現(xiàn)有的 OpenAPI 定義的 API 生成。SwaggerHub 在集成的 API 設(shè)計和文檔中將 Swagger 編輯器、UI 和 Codegen 工具帶到云端，專為使用 Swagger (OpenAPI) 規(guī)范的 API 團隊構(gòu)建。
有 Maven 和 Gradle 等構(gòu)建工具的插件，因為已經(jīng)給出了一些答案所以這里不添加
慕姐4208626
TA貢獻1852條經(jīng)驗 獲得超7個贊
只需添加一個 swagger 插件不會生成一個休息客戶端，您需要按照以下步驟操作。
以 YAML 格式寫下規(guī)范。根據(jù)規(guī)范結(jié)果，將生成。將規(guī)范另存為 YAML 文件。
添加回答
舉報
0/150
提交
取消