Spring Boot-Swagger离线文档(插件方式）

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。

项目主页：https://github.com/Swagger2Markup/swagger2markup

版本说明

JDK: 11.0.26

Spring Boot: 2.4.11

Swagger: 2.9.2

Apache Maven: 3.8.8

下载配置Apache Maven

下载Apache Maven 3.8.8

https://gitee.com/yangsunior/csdn-resources

更新配置文件settings.xml

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">
  <localRepository>C:\Users\tester\.m2\repository</localRepository>
    
  <mirrors>
    <!-- mirror
     | Specifies a repository mirror site to use instead of a given repository. The repository that
     | this mirror serves has an ID that matches the mirrorOf element of this mirror. IDs are used
     | for inheritance and direct lookup purposes, and must be unique across the set of mirrors.
     |
    <mirror>
      <id>mirrorId</id>
      <mirrorOf>repositoryId</mirrorOf>
      <name>Human Readable Name for this Mirror.</name>
      <url>http://my.repository.com/repo/path</url>
    </mirror>
     -->
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>*</mirrorOf>
        <name>阿里云公共仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
    <mirror>
      <id>nexus-aliyun</id>
      <mirrorOf>central</mirrorOf>
      <name>Nexus aliyun</name>
      <url>http://maven.aliyun.com/nexus/content/groups/public</url>
    </mirror>
    <mirror>
      <id>nexus</id>
      <name>internal nexus repository</name>
      <url>http://repo.maven.apache.org/maven2</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
    
</settings>

设置依赖下载目录: C:\Users\tester.m2\repository

添加镜像仓库地址: 3个URL镜像地址

环境变量配置maven(可选)

Idea配置Maven

pom.xml 引入依赖

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.11</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <properties>
        <swagger.version>2.9.2</swagger.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
    </dependencies>

    <build>
        <finalName>web-test-backend</finalName>
        <plugins>
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>${swagger2markup.version}</version>
                <configuration>
                    <swaggerInput>http://localhost:8081/v2/api-docs?group=dev-team</swaggerInput>
                    <outputDir>src/docs/asciidoc/generated</outputDir>
                    <config>
                        <!-- 生成asciidoc格式 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <!-- 生成markdown格式 -->
                        <!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
                        <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
                        <swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled>
                        <swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    </config>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>2.2.6</version>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>2.3.19</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>9.4.5.0</version>
                    </dependency>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj</artifactId>
                        <version>2.5.13</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>generate-pdf-doc</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                            <attributes>
                                <!--导航栏在左-->
                                <toc>left</toc>
                                <!--显示层级数-->
                                <toclevels>3</toclevels>
                                <numbered></numbered>
                                <hardbreaks></hardbreaks>
                                <sectlinks></sectlinks>
                                <sectanchors></sectanchors>
                                <generated>src/docs/asciidoc</generated>
                                <pdf-fontsdir>fonts</pdf-fontsdir>
                                <pdf-stylesdir>themes</pdf-stylesdir>
                                <pdf-style>cn-theme</pdf-style>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

说明

swaggerInput：swagger生成的接口json数据文件。
输出：
- outputFile：输出到单一文件中
- outputDir：输出到指定文件中
swagger2markup.markupLanguage：输出格式
swagger2markup.outputLanguage：语言类型：如中文（ZH），默认英语（EN）
swagger2markup.generatedExamplesEnabled：指定是否应该生成HTTP请求和响应示例，默认false
swagger2markup.inlineSchemaEnabled：是否启用参数内联
swagger2markup.pathsGroupedBy：api排序规则一般用tags排序
executions：多个执行任务配置
execution.id：不可重复

其他：参考单独生成HTML与PDF相关说明

下载依赖

maven 同步

Maven -> Sync Project，无法下载上述依赖，需要使用maven下载依赖。

package下载

下载字体与样式文件

资源地址：https://gitee.com/yangsunior/csdn-resources/tree/master/20250519-swagger2markup

生成confluence

管理员模式打开命令行窗口，执行命令

bash 复制代码

> C:\WindowsApp\apache-maven-3.8.8\bin\mvn swagger2markup:convertSwagger2markup

[INFO] Markup document written to: C:\Projects\web-test-backend\src\docs\asciidoc\generated\paths.adoc
[INFO] Markup document written to: C:\Projects\web-test-backend\src\docs\asciidoc\generated\definitions.adoc
[INFO] Markup document written to: C:\Projects\web-test-backend\src\docs\asciidoc\generated\security.adoc
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.551 s
[INFO] Finished at: 2025-05-20T16:03:19+08:00
[INFO] ------------------------------------------------------------------------

运行之后就生成出了4个不同的静态文件

生成pdf/html

bash 复制代码

> C:\WindowsApp\apache-maven-3.8.8\bin\mvn generate-resources

[INFO] Converted C:\Projects\web-test\backend\src\docs\asciidoc\generated\paths.adoc
[INFO] Converted C:\Projects\web-test\backend\src\docs\asciidoc\generated\security.adoc
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:35 min
[INFO] Finished at: 2025-05-20T16:24:30+08:00
[INFO] ------------------------------------------------------------------------

pdf目录中的中文显示为乱码，暂时未解决。

多文件合并

修改outputDir为outputFile

xml 复制代码

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>${swagger2markup.version}</version>
    <configuration>
        <swaggerInput>http://localhost:8081/v2/api-docs?group=dev-team</swaggerInput>
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <config>
            <!-- 生成asciidoc格式 -->
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
            <!-- 生成markdown格式 -->
            <!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
            <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
            <swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled>
            <swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled>
            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
    </configuration>
</plugin>

build 失败

JDK从17降低至11即可。