如何从Java生成Swagger文件并导出TypeScript模型？

一、替换Springfox为Springdoc OpenAPI #

Springfox已停止维护，改用Springdoc OpenAPI更适配Java 8和Spring Boot，既能生成包含完整接口文档的OpenAPI文件，也支持静态导出（无需运行应用）。

添加Maven依赖：

<dependencies>
    <!-- Springdoc OpenAPI 兼容Java 8的稳定版本 -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.6.15</version>
    </dependency>
</dependencies>

二、配置Maven插件生成静态Swagger YAML文件 #

使用springdoc-openapi-maven-plugin在编译阶段导出swagger-ui.yml，输出到项目构建目录：

<build>
    <plugins>
        <!-- 生成OpenAPI YAML文件 -->
        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>1.6.0</version>
            <executions>
                <execution>
                    <id>generate-openapi-yaml</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <!-- 指定你的Spring Boot主类全路径 -->
                        <springBootApplicationClass>com.yourpackage.YourApplication</springBootApplicationClass>
                        <!-- 输出文件名和路径 -->
                        <outputFileName>swagger-ui.yml</outputFileName>
                        <outputDir>${project.build.directory}/generated-resources</outputDir>
                        <openapiVersion>3.0.1</openapiVersion>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

三、配置Swagger Codegen生成Angular 13 TypeScript模型 #

用swagger-codegen-maven-plugin读取生成的YAML，仅生成TypeScript模型（跳过API接口生成，符合你自行编写Java接口的需求）：

<plugin>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.34</version>
    <executions>
        <execution>
            <id>generate-ts-models</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <!-- 输入YAML文件路径 -->
                <inputSpec>${project.build.directory}/generated-resources/swagger-ui.yml</inputSpec>
                <!-- 选择Angular TypeScript生成器 -->
                <generatorName>typescript-angular</generatorName>
                <!-- 输出到你的Angular项目模型目录（自行调整路径） -->
                <output>${project.basedir}/../angular-app/src/app/shared/models</output>
                <configOptions>
                    <angularVersion>13</angularVersion>
                    <!-- 生成TypeScript接口而非类 -->
                    <withInterfaces>true</withInterfaces>
                    <!-- 模型包名 -->
                    <modelPackage>models</modelPackage>
                    <!-- 禁用API和辅助文件生成，只保留模型 -->
                    <apis>false</apis>
                    <supportingFiles>false</supportingFiles>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

四、Java代码注解示例 #

用Springdoc注解标记模型和接口，保证生成的YAML包含完整文档信息（与Springfox效果一致）：

模型类示例： #

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户信息模型")
public class User {
    @Schema(description = "用户唯一ID", example = "1001")
    private Long id;
    
    @Schema(description = "用户名", example = "john_doe")
    private String username;
    
    // getter、setter方法省略
}

控制器接口示例： #

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {
    @Operation(summary = "根据ID查询用户", description = "通过用户ID获取详细信息")
    @ApiResponse(responseCode = "200", description = "查询成功")
    @ApiResponse(responseCode = "404", description = "用户不存在")
    @GetMapping("/users/{id}")
    public User getUser(@Parameter(description = "用户ID") @PathVariable Long id) {
        // 业务逻辑省略
        return new User();
    }
}

五、执行流程 #

1. 运行mvn compile：编译Java代码的同时，自动生成swagger-ui.yml到target/generated-resources目录。
2. 运行mvn generate-sources：读取YAML文件，生成TypeScript模型到指定的Angular项目目录。
3. （可选）将generate-ts-models执行绑定到compile阶段，这样只需运行mvn compile即可完成所有步骤。

内容的提问来源于stack exchange，提问作者Ondřej