YeLogs.com
知識庫

知識庫 / Spring / Spring Boot RSS 訂閱

使用 Swagger 生成 Spring Boot REST 客户端

REST,Spring Boot
HongKong
9
03:53 AM · Dec 06 ,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. 使用 OpenAPI Generator 生成 REST 客户端

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

與 Swagger Codegen 由 SmartBear 維護不同，OpenAPI Generator 得到了超過 40 名 Swagger Codegen 的頂級貢獻者和模板創建者（作為創始團隊成員）的社區維護。

3.1. 安裝

使用 npm 包 封裝器，通常是最簡單且最通用的安裝方法。該封裝器通過為 Java 代碼支持的命令行選項提供 CLI 封裝器來工作。安裝過程非常簡單：

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. 生成客户端

首先，OpenAPI Generator 的選項與 Swagger Codegen 幾乎相同。最主要的區別在於將 <em>-l</em> 語言標誌替換為 <em>-g</em> 生成標誌，該標誌作為生成客户端的語言參數使用。

接下來，我們使用 <em>jar</em> 命令生成一個與使用 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 (已過時) – Retrofit1/OkHttp + Gson
  • retrofit2 – Retrofit2/OkHttp + Gson
  • resttemplate – Spring RestTemplate + Jackson
  • webclient – Spring 5 WebClient + Jackson (僅 OpenAPI Generator 支持)
  • resteasy – Resteasy + Jackson
  • vertx – VertX + Jackson
  • google-api-client – Google API Client + Jackson
  • rest-assured – rest-assured + Jackson/Gson (僅 Java 8 支持)
  • native – Java native HttpClient + Jackson (僅 Java 11 支持; 僅 OpenAPI Generator 支持)
  • microprofile – Microprofile client + Jackson (僅 OpenAPI Generator 支持)

4. 生成 Spring Boot 項目

現在，讓我們創建一個新的 Spring Boot 項目。

4.1. Maven 依賴

我們將首先將 Generated API Client 庫的依賴添加到我們的項目 <em pom.xml</em> 文件中：

<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 客户端配置

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. 替代方案

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

5.1. Maven 插件

一個可以輕鬆配置在你的 <em pom.xml</em> 中的 `swagger-codegen Maven 插件，可以利用 Swagger Codegen CLI 的相同選項生成客户端。

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

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.2.3</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>swagger.yaml</inputSpec>
                <language>java</language>
                <library>resttemplate</library>
            </configuration>
        </execution>
    </executions>
</plugin>

5.2. Swagger Codegen 在線生成器 API

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

以下是一個使用簡單 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 文檔，其中包含 API 的文檔以及如何進行測試。

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.