swagger导出接口文档以及报错处理

swagger导出接口文档以及报错处理

废话少说，开干

第一步，添加依赖

聚合项目建议添加的web层pom里，不用考虑代码上传的冲突问题，这玩意一般 只用一次，用完了删了就行

看图

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

插件的依赖swagger2markup

// A code block
 <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.2.0</version>
                <configuration>
                    <!--此处端口一定要是当前项目启动所用的端口  0.0-->
                    <swaggerInput>地址如下图</swaggerInput>
                    <!-- 下方文件夹地址自己新建一下文件夹-->
                    <outputDir>src/docs/asciidoc/generated</outputDir>
                    <config>
                        <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>
            <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>
            

是寻找json内容的地址，swagger会自动生成，如图
是生成文件的地址，建议提前自己建好

在web层运行这两个指令（在那个pom里加的插件就在那个模块运行）

mvn swagger2markup:convertSwagger2markup
mvn generate-resources

---

完事了，但是并没有完全完事

一跑，哦吼，报错了。我下面把我遇到的错给各位汇报一下。

json解析异常，这是最常见的错，其他swagger导出也适用

错误原因，swaggerl李里的json地址没错，但是内容出错。
打开那个地址

心态血崩，这json有问题怎么排查？

解决方案

地址没问题，内容有问题，那我们就该内容，但页面上的json你改不了。

第一步

标签里的地址删除了，自己在web层下新建一个json文件

第二步

把json拷贝的这个json文件里,等一会，idea检索需要时间，然后 你看

有个地方编译报错了！！！这个时候我们只需要

双引括住，文件右上方不显示报错就行

第三步 ，修改检索的路径

去pom文件修改标签文档里的路径（就是我们json文件的路径）

别忘了刷新maven
结束后重启，在web下再次运行

mvn swagger2markup:convertSwagger2markup
mvn generate-resources

这俩指令

都成功了，

文件也生出来了，后面改格式啥的。就用html ,选择打开方式 → word → 另存为→
选择格式就行。