【Java】Swagger导出文档

扣钉

已于 2023-05-11 16:18:12 修改

阅读量2.9k

点赞数 1

分类专栏： Java 文章标签： java swagger2 接口

于 2021-03-02 11:33:39 首次发布

本文链接：https://blog.youkuaiyun.com/GJ454221763/article/details/114281323

版权

Java 专栏收录该内容

20 篇文章

订阅专栏

本文介绍如何使用swagger2markup和asciidoctor插件自动化生成API文档。通过配置Maven插件，实现从Swagger API Docs自动生成ASCII格式文档，并进一步转换为HTML格式。

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

导出接口文档配置：

0、确认系统的 /v2/api-docs 接口可用

1、进行swagger2markup POM配置

			<plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.1</version>
                <configuration>
                    <!-- api-docs访问url -->
                    <swaggerInput>http://ip地址:端口/项目名/v2/api-docs</swaggerInput>
                    <!-- 生成为多个文档，输出路径 -->
                    <outputDir>src/main/resources/api</outputDir>
                    <config>
                        <!-- ascii格式文档 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    </config>
                </configuration>
            </plugin>

项目根目录下cmd执行 mvn swagger2markup:convertSwagger2markup
查看并确认后缀名.adoc文件已经生成，如下图所示：

在这里插入图片描述

2、进行asciidoctor POM配置

			<!-- mvn asciidoctor:process-asciidoc -->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>src/main/resources/api</sourceDirectory>
                    <outputDirectory>src/main/resources/api/html</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
            </plugin>

项目根目录下cmd执行 mvn asciidoctor:process-asciidoc
如下图所示,接口文档已经生成！

在这里插入图片描述
注意：如果项目中配置有security，在进行.adoc文档生成过程中会进行鉴权拦截，此时只需要在security的配置中把/v2/**放开即可。

//部分代码如下：
.antMatchers("/v2/**").permitAll()