Spring Boot中不启动Web服务生成Swagger JSON并构建客户端SDK

我之前刚好搞定过一模一样的需求，分两步就能实现：先不启动Web服务生成Swagger JSON文件，再用这个文件自动生成客户端代码，全程可以整合到Maven/Gradle构建流程里，不用手动操作。

第一步：离线生成Swagger JSON文件 #

这里有两种靠谱的方法，选适合你的就行：

方法1：用Spring单元测试生成 #

这种方法不需要额外插件，利用Spring Test上下文加载Swagger配置，直接生成JSON：

1. 新建一个测试类，加载你的Spring Boot应用上下文，但不启动Web服务：

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import springfox.documentation.swagger2.mappers.ServiceModelToSwagger2Mapper;
import springfox.documentation.spring.web.plugins.Docket;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.io.File;
import java.io.IOException;

@RunWith(SpringRunner.class)
// WebEnvironment.NONE 表示不启动Web容器
@SpringBootTest(classes = YourApplication.class, webEnvironment = SpringBootTest.WebEnvironment.NONE)
public class SwaggerJsonGeneratorTest {

    @Autowired
    private Docket swaggerDocket; // 注入你配置Swagger时创建的Docket Bean

    @Autowired
    private ServiceModelToSwagger2Mapper swaggerMapper;

    @Autowired
    private ObjectMapper objectMapper;

    @Test
    public void generateSwaggerJson() throws IOException {
        // 把Docket配置转换成Swagger2模型
        var swaggerModel = swaggerMapper.mapDocumentation(swaggerDocket.getDocumentation());
        // 写入到目标文件，路径可以自己调整，比如target目录
        objectMapper.writeValue(new File("target/swagger.json"), swaggerModel);
    }
}

2. 运行这个测试类，target/swagger.json就会生成了。如果要整合到构建流程，可以把这个测试加到mvn test的执行序列里。

方法2：用Maven插件自动生成 #

如果你不想写测试类，可以用swagger-maven-plugin直接扫描你的控制器代码生成JSON：

在pom.xml里添加插件配置：

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.8</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>true</springmvc> <!-- 因为是Spring MVC/Spring Boot项目 -->
                <locations>com.your.project.controller</locations> <!-- 你的控制器所在包 -->
                <schemes>http,https</schemes>
                <host>localhost:8080</host>
                <basePath>/api</basePath> <!-- 你的API基础路径 -->
                <info>
                    <title>Your API Documentation</title>
                    <version>1.0.0</version>
                </info>
                <swaggerDirectory>target/swagger</swaggerDirectory> <!-- 生成文件的目录 -->
                <swaggerFileName>swagger.json</swaggerFileName> <!-- 生成的文件名 -->
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>process-resources</phase> <!-- 确保在生成客户端代码前执行 -->
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

运行mvn process-resources，插件会自动扫描你的控制器，生成target/swagger/swagger.json文件。

第二步：用Swagger JSON生成客户端类 #

推荐用OpenAPI Generator（它是Swagger Codegen的维护分支，功能更全），可以直接集成到Maven构建里：

在pom.xml添加OpenAPI Generator插件：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.2.0</version>
    <executions>
        <execution>
            <id>generate-java-client</id>
            <phase>generate-sources</phase> <!-- 在生成源码阶段执行 -->
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.build.directory}/swagger/swagger.json</inputSpec> <!-- 第一步生成的JSON路径 -->
                <generatorName>java</generatorName> <!-- 生成Java客户端，也可以选kotlin/python等 -->
                <output>${project.build.directory}/generated-sources/openapi</output> <!-- 生成代码的目录 -->
                <apiPackage>com.your.project.client.api</apiPackage> <!-- API接口类的包路径 -->
                <modelPackage>com.your.project.client.model</modelPackage> <!-- 模型类的包路径 -->
                <configOptions>
                    <dateLibrary>java8</dateLibrary>
                    <library>resttemplate</library> <!-- 用Spring RestTemplate实现，也可以选feign -->
                    <interfaceOnly>false</interfaceOnly> <!-- 是否只生成接口，默认false生成完整实现 -->
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

整合整个构建流程 #

现在只需要运行mvn clean install，就会自动完成：

1. 扫描控制器生成Swagger JSON文件
2. 用JSON文件生成客户端代码
   全程不需要启动Web服务，完全离线完成。

注意事项 #

• 如果你的Spring Boot版本是2.6+，Springfox可能有路径匹配的兼容性问题，需要在application.properties里添加：spring.mvc.pathmatch.matching-strategy=ant_path_matcher
• OpenAPI Generator支持很多配置选项，比如生成Feign客户端只需要把<library>改成feign，生成响应式客户端可以选webclient
• 如果你用Gradle，对应的插件配置类似，核心逻辑和Maven一致

内容的提问来源于stack exchange，提问作者Tech User