RuoYi-Vue-fast后端接口文档导出：PDF与HTML格式生成

RuoYi-Vue-fast后端接口文档导出：PDF与HTML格式生成

【免费下载链接】RuoYi-Vue-fast :tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue & Element 的前后端分离权限管理系统 项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue-fast

你是否还在为项目接口文档的导出格式发愁？开发团队需要HTML格式便于在线查阅，而客户又要求PDF格式进行归档？本文将详细介绍如何在RuoYi-Vue-fast项目中一键生成两种格式的接口文档，让你轻松应对不同场景需求。读完本文后，你将掌握Swagger配置优化、文档导出工具集成及自动化部署的完整流程。

一、Swagger接口文档基础配置

RuoYi-Vue-fast项目已内置Swagger接口文档支持，核心配置位于src/main/java/com/ruoyi/framework/config/SwaggerConfig.java。该类通过Spring Boot的自动配置机制，实现了接口文档的自动化生成。

1.1 核心配置解析

Swagger配置类主要包含三个关键部分：

• API文档元信息配置（标题、描述、版本等）
• 安全上下文设置（支持JWT令牌认证）
• 接口扫描策略（基于@ApiOperation注解）

关键代码片段：

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.OAS_30)
            .enable(enabled)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts())
            .pathMapping(pathMapping);
}

1.2 配置文件参数

Swagger的开关和路径映射可通过配置文件调整，默认配置如下：

# 是否开启Swagger
swagger.enabled=true
# 接口文档路径映射
swagger.pathMapping=/

二、HTML格式文档导出

2.1 在线接口文档访问

项目启动后，可通过以下地址访问Swagger UI界面：

http://localhost:8080/swagger-ui/index.html

该界面提供了完整的接口列表、参数说明和在线调试功能，适合开发团队内部使用。

2.2 HTML文档保存方法

1. 在Swagger UI界面点击右上角的Expand Operations展开所有接口
2. 按下Ctrl+S保存当前页面为HTML文件
3. 选择"网页，仅HTML"格式保存

保存后的HTML文件可直接在浏览器中打开，无需依赖后端服务。

三、PDF格式文档导出

3.1 依赖添加

在pom.xml中添加PDF导出所需依赖：

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
</dependency>
<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-extension-asciidoctor</artifactId>
    <version>1.3.3</version>
</dependency>

3.2 导出工具类实现

创建PDF导出工具类src/main/java/com/ruoyi/common/utils/PdfExportUtils.java：

public class PdfExportUtils {
    public static void exportSwaggerToPdf(String swaggerUrl, String outputPath) throws Exception {
        // 从Swagger JSON生成AsciiDoc文档
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
        
        Swagger2MarkupConverter.from(new URL(swaggerUrl))
                .withConfig(config)
                .build()
                .toFile(Paths.get(outputPath + "/api"));
        
        // 将AsciiDoc转换为PDF
        Asciidoctor asciidoctor = Asciidoctor.Factory.create();
        Options options = new Options();
        options.setBackend("pdf");
        options.setDestinationDir(Paths.get(outputPath).toFile());
        asciidoctor.convertFile(Paths.get(outputPath + "/api.adoc").toFile(), options);
    }
}

3.3 导出接口实现

在测试控制器中添加导出接口src/main/java/com/ruoyi/project/tool/swagger/TestController.java：

@ApiOperation("导出接口文档为PDF格式")
@GetMapping("/export/pdf")
public AjaxResult exportPdf() {
    try {
        String swaggerUrl = "http://localhost:8080/v3/api-docs";
        String outputPath = System.getProperty("user.home") + "/documents";
        PdfExportUtils.exportSwaggerToPdf(swaggerUrl, outputPath);
        return AjaxResult.success("PDF文档导出成功，路径：" + outputPath + "/api.pdf");
    } catch (Exception e) {
        return AjaxResult.error("PDF文档导出失败：" + e.getMessage());
    }
}

四、自动化导出配置

4.1 集成到项目构建流程

在pom.xml中添加maven-assembly-plugin配置，实现构建时自动导出文档：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>3.3.0</version>
    <executions>
        <execution>
            <id>export-docs</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
            <configuration>
                <descriptors>
                    <descriptor>src/main/assembly/docs.xml</descriptor>
                </descriptors>
            </configuration>
        </execution>
    </executions>
</plugin>

4.2 文档导出脚本

创建导出脚本doc/export-docs.sh：

#!/bin/bash
# 启动项目
nohup java -jar target/ruoyi-admin.jar &
# 等待项目启动
sleep 30
# 导出HTML文档
wget -O doc/api.html http://localhost:8080/swagger-ui/index.html
# 调用PDF导出接口
curl http://localhost:8080/export/pdf
# 停止项目
kill -9 $(ps -ef | grep ruoyi-admin.jar | grep -v grep | awk '{print $2}')

五、常见问题解决

5.1 中文乱码问题

在swagger2markup配置中添加中文字体支持：

.withConfig(new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.ZH)
        .withAsciiDocDocExtensions(
            Arrays.asList(new AsciiDocExtension(), new SpringRestDocsExtension()))
        .build())

5.2 认证问题

Swagger配置已包含JWT认证支持，在导出PDF前需先获取令牌并添加到请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

六、总结与展望

本文详细介绍了RuoYi-Vue-fast项目中接口文档的导出方法，包括HTML格式的直接保存和PDF格式的生成流程。通过集成swagger2markup工具，实现了接口文档的自动化导出，提高了开发效率。

未来可以进一步优化：

1. 添加文档版本控制
2. 实现多语言文档导出
3. 集成到CI/CD流程，实现每次构建自动更新文档

官方环境使用手册：doc/若依环境使用手册.docx

项目源码地址：https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue-fast

【免费下载链接】RuoYi-Vue-fast :tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue & Element 的前后端分离权限管理系统 项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue-fast