在IDEA上使用Swagger生成PDF以及HTML接口文档

最新推荐文章于 2024-06-20 16:22:10 发布

原创最新推荐文章于 2024-06-20 16:22:10 发布 · 1.9k 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#swagger #IDEA

本文介绍了如何在IntelliJ IDEA(IntelliJ IDEA)上使用Swagger生成PDF和HTML接口文档。首先，需要在POM.XML文件中添加Swagger的相关依赖，并配置Swagger2Markup插件。接着，通过Maven面板运行插件，生成ASCIIDOC源文件。然后，执行额外的步骤以生成HTML和PDF文档。在实际操作中，可能会遇到汉字显示问题、API地址获取和IDEA报错等问题，文中也给出了相应的解决建议。

编辑POM.XML文件配置相关依赖

		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

        <!-- ********************* swagger导出PDF/HTML所需依赖 START ********************************* -->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
        <!-- ********************* swagger导出PDF/HTML所需依赖 END ********************************* -->

首先我们需要在pom.xml中导入swagger相关的依赖包。

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

此外我们还需要在pom.xml配置生成PDF和HTML以及源文件ASCIIDOC的插件。

生成文件

在这里插入图片描述
在IDEA的右侧的maven中选择相应工程点开后选择swagger2markup插件点击运行，就可以根据在pom中配置的路径位置生成相应的源文件。如下图所示。

当然此时的html和pdf连文件夹都没有生成，所以我们还需要运行之前配置的生成html和pdf的文件来生成相应的html和pdf。如下图所示。
在这里插入图片描述

可能会遇到的问题

第一个可能会遇到的问题是生成的PDF生成的格式可能由于编码问题导致有部分汉字无法显示出来，所以我选择了使用html版本。
第二个可能会在‘http://localhost://v2/api-docs’第一次用的朋友可能不知道他是怎么来的，这个地址路径其实可以去你本地的swagger页面上去取，就在页面端的标题下面。
第三个是在运行第二个插件的时候IDEA的控制台会出现不兼容不支持的问题，报什么IO/**** not support这种问题，其实这个我也不知道怎么解决。反正就是瞎鼓捣，等了一会之后就ok了。