基于Swagger生成Spring Boot项目

1. 引言

本文将使用 Swagger Codegen 和 OpenAPI Generator 从 OpenAPI/Swagger规范文件生成REST客户端。

我们还将创建一个Spring Boot项目，其中会使用这些生成的类。所有示例都将基于 Swagger Petstore API实现。

2. 使用Swagger Codegen生成REST客户端

Swagger提供了一个实用工具jar包，支持为多种编程语言和框架生成REST客户端。

2.1 下载Jar文件

最新版本请查看 swagger-codegen-cli 并下载最新版。

2.2 生成客户端

执行以下命令生成客户端：

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

参数说明：

-i：Swagger源文件URL或路径
--api-package、--model-package、--invoker-package：生成类的包名
--group-id、--artifact-id、--artifact-version：Maven项目属性
-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 2.0/3.x文档生成50+种客户端。它由社区维护，创始团队包含40多位Swagger Codegen顶级贡献者。

3.1 安装

推荐使用npm包安装（跨平台）：

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

或下载JAR文件：

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基本一致，主要区别是-l替换为-g。生成等价客户端：

java -jar openapi-generator-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  --api-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

支持的Java库（比Swagger Codegen更多）：

✅ 所有Swagger Codegen支持的库
webclient – Spring 5 WebClient + Jackson（独有）
vertx – VertX + Jackson（独有）
google-api-client – Google API Client + Jackson（独有）
rest-assured – rest-assured + Jackson/Gson（仅Java 8）
native – Java原生HttpClient + Jackson（仅Java 11，独有）
microprofile – Microprofile客户端 + Jackson（独有）

4. 创建Spring Boot项目

4.1 Maven依赖

在pom.xml添加生成的API客户端依赖：

<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类：

@Autowired
private PetApi petApi;

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

5. 替代方案

除了CLI工具，还有其他生成REST客户端的方式：

5.1 Maven插件

swagger-codegen Maven插件可在pom.xml中配置：

<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

向http://generator.swagger.io/api/gen/clients/java发送POST请求：

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格式客户端代码的下载链接。所有CLI选项都支持。

5.3 OpenAPI Generator在线生成API

类似地，向http://api.openapi-generator.tech/api/gen/clients/java发送请求：

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

响应同样包含ZIP下载链接。文档见GitHub。

6. 总结

Swagger Codegen和OpenAPI Generator能快速生成多语言、多库的REST客户端。可通过CLI工具、Maven插件或在线API实现。

示例项目包含三个Maven模块：生成的Swagger客户端、生成的OpenAPI客户端和Spring Boot应用。完整代码见GitHub。

Persistence

REST

Security