将Swagger导出HTML、PDF和MARKDOWN

最新推荐文章于 2025-06-29 09:13:06 发布

StudyNetJava

最新推荐文章于 2025-06-29 09:13:06 发布

阅读量1.3w

点赞数 4

CC 4.0 BY-SA版权

分类专栏： swagger springboot 文章标签： swagger swagger生成文档离线文档 springboot html5

本文链接：https://blog.youkuaiyun.com/qq_16256793/article/details/79522749

本文介绍了如何使用Knife4j工具增强Swagger功能，支持导出PDF、MD、Word和HTML格式的离线文档。通过在SpringBoot项目中引入依赖并配置，可以方便地管理和下载API文档。同时，文章提到了Swagger分组的重要性以及在不同生成文档过程中可能遇到的问题和解决方案。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

今天突然了解了另外一种方式，knife4j工具，集成了swagger，页面比swagger功能更多点，并且支持下载多种文档形式，pdf、md、word、html

1.首先是引入依赖，我用的最新的版本2.0.3

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-ui</artifactId>
            <version>2.0.3</version>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.3</version>
        </dependency>

2.启动工程后，访问此地址：http://localhost:8080/doc.html?plus=1

3.在左上角可以切换分组，下面有文档管理，离线文档，就可以下载文档了

----------------------------------------------------------------------------------------------------------------------------------------------------------------------------

在网上突然看到了有别的方式，在这里记录一下，比这个简单很多，容易理解的

1.在依赖中还是有swagger2Markup

<dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

2.在pom.xml的build中增加插件，这个插件是用于生成adoc文件的，一共四个

1.definitions.adoc 保存request的对象体信息

2.overview.adoc 整体的描述

3.paths.adoc 所有接口的具体信息

4.security.adoc 几乎无用

里面的swaggerInput配置，配置获取swagger.json的url，ip和port需要修改为对应的，对swagger了解比较多的，swagger会有分组的配置，如果配置了分组，需要将url带上分组信息，如http://localhost:8082/v2/api-docs?group=xxxx，如果配置了分组，而没有group参数，在执行命令时会不成功

outputDir配置了生成出来的文件的路径，试过了一下，建议不要配置在src下面，在删除内容的时候，容易将src都删除了，很坑

<plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.2.0</version>
                <configuration>
                    <!--此处端口一定要是当前项目启动所用的端口-->
                    <swaggerInput>http://localhost:8082/v2/api-docs</swaggerInput>
                    <outputDir>src/docs/asciidoc/generated</outputDir>
                    <config>
                        <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>

3.也是在build中增加插件，配置了生成html和pdf的相关配置

<!--此插件生成HTML和PDF-->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.10.1</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <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>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

4.上面的配置完成后，执行命令