做了个项目扩展 SpringFox 改善 Swagger 文档生成

GitHub：SpringFox-Plus： https://github.com/hadix-lin/springfox-plus

这个项目默认集成了 swagger-ui，也可以配合 swagger-bootstrap-ui 使用。

请有空的同学帮忙测试一下，有问题请在这里或 github 返回，谢谢。

概述

SpringFox是一个优秀的项目,为基于 Spring 的 RestAPI 文档生成提供了强大的支持,另外还具有优秀的扩展机制.

SpringFox 原生提供的插件,只能从 Swagger-Annotation 注解中提取描述文档.使用注解提供文档有如下缺陷:

1. 注解是运行时依赖,对代码有侵入性
2. 常规情况下注解的绝大部分属性是不需要的
3. 注解的名称冗长(@ApiParam,@ApiOperation,@ApiModelProperty)
4. 代码原本可能已经提供了 javadoc 注释,跟注解内容重复

SpringFox-Plus为 Spring-Fox 提供了读取 javadoc 作为 API 文档的能力.常规情况下可以替代@ApiParam,@ApiOperation,@ApiModelProperty等注解的使用.80%以上的 API 文档也是通过这三个注解提供的.

使用方法

1. 在项目中添加 maven 依赖

   <!-- springfox-plus -->
   <dependency>
       <groupId>io.github.hadix-lin</groupId>
       <artifactId>springfox-plus</artifactId>
       <version>1.0.2-SNAPSHOT</version>
   </dependency>
   
   <!-- 如果使用 spring-boot -->
   <dependency>
       <groupId>io.github.hadix-lin</groupId>
       <artifactId>springfox-plus-spring-boot-starter</artifactId>
       <version>1.0.2-SNAPSHOT</version>
   </dependency>
   
   <!-- 使用 SNAPSHOT 版本需要声明如下仓库 -->
   <repositories>
     <repository>
       <id>oss</id>
       <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
     </repository>
   </repositories>
   

2. 导入 Bean 声明

   // 方法一 : 在您的 @Configuration 类上加上如下代码
   @Import(io.github.hadixlin.springfoxplus.SpringfoxPlusConfiguration.class)
   
   // 方法二 : 确保`JavaDocAutoConfiguration`在 Bean 扫描范围内
   @ComponentScan(basepackages="io.github.hadixlin.springfoxplus")
   
   // 方法三 : 项目使用 SpringBoot,引入 maven 依赖后,不需要额外配置代码
   // 可以参考源码中的"springfox-plus-sample"项目
   

3. 使用 maven 插件执行目标:springfox-plus:javadoc

   插件配置: 下面的配置将javadoc默认绑定到了compile阶段.所以在执行mvn compile时即可解析 javadoc

   <build>
     <plugins>
       <plugin>
         <groupId>io.github.hadix-lin</groupId>
         <artifactId>springfox-plus-maven-plugin</artifactId>
         <version>${springfox-plus.version}</version>
         <executions>
           <execution>
             <id>javadoc</id>
             <phase>compile</phase>
             <goals>
               <goal>javadoc</goal>
             </goals>
             <configuration>
               <packages>
                 <!-- 指定要扫描的包,没有该配置默认扫描所有的 java 源文件-->
                 <p>io.github.hadixlin.springfoxplus</p>
               </packages>
             </configuration>
           </execution>
         </executions>
       </plugin>
     </plugins>
   </build>
   

   配置好 maven 插件后,在 pom.xml 所在目录中执行下面的命令即可

   mvn springfox-plus:javadoc 
   # 或
   mvn compile
   

4. 正常运行项目,使用 swagger-ui 查看 API 文档即可,可以看到 API 方法的的 javadoc 被读作作为 API 文档展示.

   swagger-ui 可以直接通过http://host:port/swagger-ui.html来访问