生成帶 Swagger 的 Spring Boot REST 客户端

REST,Spring Boot
Remote
1
11:02 AM · Dec 01 ,2025

1. 簡介

在本文中，我們將使用 Swagger Codegen 和 OpenAPI Generator 項目來從 OpenAPI/Swagger spec 文件生成 REST 客户端。

此外，我們還將創建一個 Spring Boot 項目，其中將使用生成的類。

我們還將使用 Swagger Petstore API 示例進行一切操作。

2. 生成帶有 Swagger Codegen 的 REST 客户端

Swagger 提供一個實用 JAR 包，允許我們為各種編程語言和多個框架生成 REST 客户端。

2.1. 下載 JAR 文件

要獲取最新版本，請查看 swagger-codegen-cli 構件並下載最新版本。

2.2. 生成客户端

通過執行命令 java -jar swagger-code-gen-cli.jar generate: 生成我們的客户端。

java -jar swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  --api-package com.baeldung.petstore.client.api \
  --model-package com.baeldung.petstore.client.model \
  --invoker-package com.baeldung.petstore.client.invoker \
  --group-id com.baeldung \
  --artifact-id spring-swagger-codegen-api-client \
  --artifact-version 0.0.1-SNAPSHOT \
  -l java \
  --library resttemplate \
  -o spring-swagger-codegen-api-client

提供的參數包括：

  • 源 Swagger 文件 URL 或路徑 – 使用 -i 參數提供
  • 生成類名包的名稱 – 使用 –api-package、–model-package、–invoker-package
  • 生成的 Maven 項目屬性 –group-id、–artifact-id、–artifact-version
  • 生成客户端的編程語言 – 使用 -l 參數提供
  • 實現框架 – 使用 –library 參數提供
  • 輸出目錄 – 使用 -o 參數提供

要列出所有與 Java 相關的選項，請鍵入以下命令：

java -jar swagger-codegen-cli.jar config-help -l java

Swagger Codegen 支持以下 Java 庫（HTTP 客户端和 JSON 處理庫的組合）：

  • jersey1 – Jersey1 + Jackson
  • jersey2 – Jersey2 + Jackson
  • feign – OpenFeign + Jackson
  • okhttp-gson – OkHttp + Gson
  • retrofit (已過時) – Retrofit1/OkHttp + Gson
  • retrofit2 – Retrofit2/OkHttp + Gson
  • rest-template – Spring RestTemplate + Jackson
  • rest-easy – Resteasy + Jackson

在本文檔中，我們選擇了 rest-template，因為它是一個 Spring 生態系統的一部分。

3. Generate REST Client With OpenAPI Generator

OpenAPI Generator 是 Swagger Codegen 的一個分支，能夠從任何 OpenAPI Specification 2.0/3.x 文檔生成 50+ 客户端。

與 Swagger Codegen 由 SmartBear 維護，OpenAPI Generator 則由一個社區維護，該社區包括 Swagger Codegen 的 40 多名頂級貢獻者和模板創建者作為創始團隊成員。

3.1. Installation

使用 npm 包作為包裝器，這是最簡單和最便攜的安裝方法，它通過在命令行選項的支持之上提供一個 CLI 包裝器來完成，該包裝器適用於 Java 代碼。安裝非常簡單：

npm install @openapitools/openapi-generator-cli -g

對於想要獲得 JAR 文件的人，可以在 Maven Central 找到它。現在讓我們下載它：

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.2.3/openapi-generator-cli-4.2.3.jar \
  -O openapi-generator-cli.jar

3.2. Generate Client

首先，OpenAPI Generator 的選項與 Swagger Codegen 非常相似。最顯著的區別是使用 -g 選項代替 -l 選項作為生成客户端的語言參數。

接下來，讓我們使用 jar 命令生成與使用 Swagger Codegen 生成的客户端相當的客户端：

java -jar openapi-generator-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  --api-package com.baeldung.petstore.client.api \
  --model-package com.baeldung.petstore.client.model \
  --invoker-package com.baeldung.petstore.client.invoker \
  --group-id com.baeldung \
  --artifact-id spring-openapi-generator-api-client \
  --artifact-version 0.0.1-SNAPSHOT \
  -g java \
  -p java8=true \
  --library resttemplate \
  -o spring-openapi-generator-api-client

要列出所有與 Java 相關的選項，請鍵入以下命令：

java -jar openapi-generator-cli.jar config-help -g java

OpenAPI Generator 支持 Swagger CodeGen 中所有相同的 Java 庫，以及一些額外的庫。以下 Java 庫（HTTP 客户端和 JSON 處理庫的組合）受 OpenAPI Generator 支持：

  • jersey1 – Jersey1 + Jackson
  • jersey2 – Jersey2 + Jackson
  • feign – OpenFeign + Jackson
  • okhttp-gson – OkHttp + Gson
  • retrofit (Obsolete) – Retrofit1/OkHttp + Gson
  • retrofit2 – Retrofit2/OkHttp + Gson
  • resttemplate – Spring RestTemplate + Jackson
  • webclient – Spring 5 WebClient + Jackson (OpenAPI Generator only)
  • resteasy – Resteasy + Jackson
  • vertx – VertX + Jackson
  • google-api-client – Google API Client + Jackson
  • rest-assured – rest-assured + Jackson/Gson (Java 8 only)
  • native – Java native HttpClient + Jackson (Java 11 only; OpenAPI Generator only)
  • microprofile – Microprofile client + Jackson (OpenAPI Generator only)

4. 生成 Spring Boot 項目現在我們來創建一個新的 Spring Boot 項目。

4.1. Maven 依賴首先，我們將 Generated API Client 庫的依賴項添加到我們的項目中的 pom.xml 文件中：

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>spring-swagger-codegen-api-client</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

4.2. 將 API 類配置為 Spring Bean要訪問生成的類，我們需要將它們配置為 Bean：

@Configuration
public class PetStoreIntegrationConfig {

    @Bean
    public PetApi petApi() {
        return new PetApi(apiClient());
    }

    @Bean
    public ApiClient apiClient() {
        return new ApiClient();
    }
}

4.3. API Client 配置 ApiClient 類用於配置身份驗證、API 的基本路徑、常用標頭，並負責執行所有 API 請求。

例如，如果您使用 OAuth：

@Bean
public ApiClient apiClient() {
    ApiClient apiClient = new ApiClient();

    OAuth petStoreAuth = (OAuth) apiClient.getAuthentication("petstore_auth");
    petStoreAuth.setAccessToken("special-key");

    return apiClient;
}

4.4. Spring 主應用程序我們需要導入新創建的配置：

@SpringBootApplication
@Import(PetStoreIntegrationConfig.class)
public class PetStoreApplication {
    public static void main(String[] args) throws Exception {
        SpringApplication.run(PetStoreApplication.class, args);
    }
}

4.5. API 使用由於我們已將 API 類配置為 Bean，因此我們可以自由地在我們的 Spring 託管類中注入它們：

@Autowired
private PetApi petApi;

public List<Pet> findAvailablePets() {
    return petApi.findPetsByStatus(Arrays.asList("available"));
}

5. 替代方案

除了執行 Swagger Codegen 或 OpenAPI Generator CLI 之外，還有其他生成 REST 客户端的方法。

5.1. Maven 插件

一個 swagger-codegen Maven 插件，可以輕鬆配置在你的 pom.xml 中，允許以 Swagger Codegen CLI 的相同選項生成客户端。

這是一個我們可以包含在項目 pom.xml 中的基本代碼片段，以自動生成客户端：


    
        io.swagger
        swagger-codegen-maven-plugin
        2.2.3
        
            
                
                    generate
                
                
                    swagger.yaml
                    java
                    resttemplate

5.2. Swagger Codegen 在線生成器 API

一個已發佈 API，通過向 URL http://generator.swagger.io/api/gen/clients/java 發送 POST 請求，並附帶請求正文中其他選項，幫助我們生成客户端。

以下是一個使用簡單的 curl 命令的示例：


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

響應將是 JSON 格式，包含一個包含生成的客户端代碼的 zip 格式的下載鏈接。 您可以傳遞 Swagger Codegen CLI 中使用的相同選項來自定義輸出客户端。

https://generator.swagger.io 包含有關 API 的 Swagger 文檔，其中我們可以檢查其文檔並嘗試使用它。

5.3. OpenAPI Generator 在線生成器 API

與 Swagger Godegen 類似，OpenAPI Generator 也具有在線生成器。 讓我們使用簡單的 curl 命令執行一個示例：


curl -X POST -H "content-type:application/json" \
  -d '{"openAPIUrl":"http://petstore.swagger.io/v2/swagger.json"}' \
  http://api.openapi-generator.tech/api/gen/clients/java

響應，格式為 JSON，將包含指向生成的客户端代碼的 zip 格式下載鏈接。 您可以傳遞 Swagger Codegen CLI 中使用的相同選項來自定義輸出客户端。

https://github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md 包含有關 API 的文檔。

6. 結論

Swagger Codegen 和 OpenAPI Generator 能夠幫助您快速為 API 生成 REST 客户端，支持多種語言和您選擇的庫。我們可以使用 CLI 工具、Maven 插件或在線 API 生成客户端庫。

這是一個基於 Maven 的項目，包含三個 Maven 模塊：生成的 Swagger API 客户端、生成的 OpenAPI 客户端和 Spring Boot 應用程序。

user avatar
0 位用戶收藏了這個故事！
收藏

發佈 評論

Some HTML is okay.