JarCasting
JarCasting JarCasting

springfox-plus

An extension of SpringFox that supports read javadoc as API document

License

License
GroupId

GroupId

io.github.hadix-lin
ArtifactId

ArtifactId

springfox-plus-parent
Last Version

Last Version

1.0.1
Release Date

Release Date
Type

Type

pom
Description

Description

springfox-plus
An extension of SpringFox that supports read javadoc as API document
Project URL

Project URL

https://github.com/hadix-lin/springfox-plus
Source Code Management

Source Code Management

https://github.com/hadix-lin/springfox-plus

Download springfox-plus-parent

Filename Size
springfox-plus-parent-1.0.1.pom 6 KB
Browse

How to add to project

<!-- https://jarcasting.com/artifacts/io.github.hadix-lin/springfox-plus-parent/ -->
<dependency>
    <groupId>io.github.hadix-lin</groupId>
    <artifactId>springfox-plus-parent</artifactId>
    <version>1.0.1</version>
    <type>pom</type>
</dependency>
// https://jarcasting.com/artifacts/io.github.hadix-lin/springfox-plus-parent/
implementation 'io.github.hadix-lin:springfox-plus-parent:1.0.1'
// https://jarcasting.com/artifacts/io.github.hadix-lin/springfox-plus-parent/
implementation ("io.github.hadix-lin:springfox-plus-parent:1.0.1")
'io.github.hadix-lin:springfox-plus-parent:pom:1.0.1'
<dependency org="io.github.hadix-lin" name="springfox-plus-parent" rev="1.0.1">
  <artifact name="springfox-plus-parent" type="pom" />
</dependency>
@Grapes(
@Grab(group='io.github.hadix-lin', module='springfox-plus-parent', version='1.0.1')
)
libraryDependencies += "io.github.hadix-lin" % "springfox-plus-parent" % "1.0.1"
[io.github.hadix-lin/springfox-plus-parent "1.0.1"]

Dependencies

compile (1)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib-jdk8 jar 1.3.30

Project Modules

  • springfox-plus-javadoc-core
  • springfox-plus-javadoc-parser
  • springfox-plus-maven-plugin
  • springfox-plus-support
  • springfox-plus
  • springfox-plus-spring-boot-starter

SpringFox-Plus

FOSSA Status

概述

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>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>
<pluginRepositories>
  <pluginRepository>
    <id>oss-plugin</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </pluginRepository>
</pluginRepositories>

  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. 如果有项目中有大量的API接口,同时展示在一个页面上可能不太好看,加载也会比较慢.这时候就需要使用API分组

    <!-- 确保springfox-plus-support在项目的编译时依赖中 -->
<dependency>
    <groupId>io.github.hadix-lin</groupId>
    <artifactId>springfox-plus-support</artifactId>
    <version>[the last version]</version>
</dependency>

    然后在您的项目中定义Bean来描述分组情况,例如添加一个"后台管理接口分组"

    @Bean
public ApiDocGroup adminGroup() {
    // 定义分组
    ApiDocGroup group = new ApiDocGroup("后台管理接口分组");
    // prefix和pattern二选一即可,同时设置优先使用prefix
    group.setPathPrefix(new String[] {"/smaple"});
    group.setPathPattern("/sample.*");

    // 可选配置文档说明信息
    ApiDocInfo info = new ApiDocInfo();
    info.setTitle("后台管理接口文档");
    info.setDescription("这里可以添加详细的文档信息,可以是html格式");
    info.setContact("作者的名字");
    info.setVersion("v1.0");
    group.setApiDocInfo(info);
    return group;
}

  2. 项目发布到生产环境时,应该是不希望开放API文档服务的.有两种方法可以达到该目的

    • 如果您的项目是用springfox-plus-spring-boot-starter,那么可以在配置文件(通常是application.properties)中加入:

      springfox-plus.enable=false

    • 或者使用maven profile来管理构建,指定profile来构建包含springfox-plus

        <profiles>
    <profile>
      <id>with-api-doc</id>
      <dependencies>
        <dependency>
          <groupId>io.github.hadix-lin</groupId>
          <artifactId>springfox-plus-spring-boot-starter</artifactId>
          <version>[the last version]</version>
        </dependency>
      </dependencies>
    </profile>
  </profiles>
  <!-- springfox-plus-support 一定要包含在编译时依赖中 -->
  <dependencies>
    <dependency>
      <groupId>io.github.hadix-lin</groupId>
      <artifactId>springfox-plus-support</artifactId>
      <version>[the last version]</version>
    </dependency>
  </dependencies>

      然后在开发阶段构建时使用如下命令:

      mvn package -P with-api-doc

License

FOSSA Status

Versions

Version
1.0.1
1.0.0
0.0.1