V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
hadixlin
V2EX  ›  程序员

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

  •  
  •   hadixlin · 2019-08-04 00:45:47 +08:00 · 2244 次点击
    这是一个创建于 1699 天前的主题,其中的信息可能已经有所发展或是发生改变。

    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来访问

    1 条回复    2019-08-04 06:38:06 +08:00
    luckylo
        1
    luckylo  
       2019-08-04 06:38:06 +08:00 via Android
    好东西,先收藏看看
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   2661 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 24ms · UTC 15:18 · PVG 23:18 · LAX 08:18 · JFK 11:18
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.