基于Maven的YAPI文档生成插件yapidoc-maven-plugin

迈不过友情╰ 2022-09-05 13:58 236阅读 0赞

# 功能介绍 #

自动扫描Spring的Controller代码并生成OpenAPI文档，无代码侵入。  
对比与Swageer的代码侵入显得更加简洁。  
项目地址：[https://gitee.com/laofeng/yapidoc-maven-plugin][https_gitee.com_laofeng_yapidoc-maven-plugin]

# 诞生原因 #

在开发的过程中，尤其是联调的过程中，接口出入参的修改是很频繁的一件事。这就导致开发过程中，修改了接口参数缺忘记修改接口文档。  
因此需要一个工具能够自动读取Java类中的注释来生成文档。

# 对比Swagger #

Springfox的代码侵入性太强了，使得代码一点优雅性都没有，注解上写了说明那还要写注释么？  
而且Springfox的功能太强大，几乎能够生成所有类型的文档，但实际使用中最多的还是使用JSON作为DSL来描述，所以这个项目目前只支持了使用JSON进行出入参描述。

# 基本特性 #

yapidoc最终会把扫描路径下的所有controller解析成OpenApi 3.0协议。

controller解析:会扫描带有@Controller和@RestController的类。

URL解析:SpringMvc中定义的基本Mapping

入参解析: 如果使用@RequestBody注解则解析成JSON格式、否则就解析成param格式。

出参解析:会把所有的类都解析成JSON格式。

# Maven插件使用方式 #

插件引入：

<plugin>
        <artifactId>yapidoc-maven-plugin</artifactId>
        <groupId>com.eeeffff.yapidoc</groupId>
        <version>1.0.1</version>
        <configuration>
            
            <yapiUrl>http://yapi.xxx.com/</yapiUrl>
            
            <yapiProjectToken>12345654345654334565434</yapiProjectToken>
            
            <controllers><controllers>
            
            <packages><packages>
        </configuration>
        <executions>
            <execution>
                <id>doc-dependencies</id>
                <phase>prepare-package</phase>
                <goals>
                    <goal>yapidoc</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

插件默认为prepare-package生命周期，运行有两种方式：

mvn yapidoc:yapidoc

或

mvn prepare-package -Dmaven.test.skip

以下为自动生成YAPI接口定义文档的截图示例：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZlbmdsaWJpbmc_size_16_color_FFFFFF_t_70_pic_center]

[https_gitee.com_laofeng_yapidoc-maven-plugin]: https://gitee.com/laofeng/yapidoc-maven-plugin
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZlbmdsaWJpbmc_size_16_color_FFFFFF_t_70_pic_center]: /images/20220829/e1fbed1fbfa742e8aae4e26c7a551672.png