springboot之swagger快速启动

简介

介绍

可能大家都有用过swagger,可以通过ui页面显示接口信息，快速和前端进行联调。

没有接触的小伙伴可以参考文章进行了解下。

多应用

当然在单个应用大家可以配置swaggerconfig类加载下builddocket,就可以快速构建好swagger了。

代码大致如下：

/**
 * swagger2配置类
 * 在与spring boot集成时，放在与application.java同级的目录下。
 * 通过@configuration注解，让spring来加载该类配置。
 * 再通过@enableswagger2注解来启用swagger2。
 */
@configuration
@enableswagger2
public class swaggerconfig {
    
    /**
     * 创建api应用
     * apiinfo() 增加api相关信息
     * 通过select()函数返回一个apiselectorbuilder实例,用来控制哪些接口暴露给swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立api的目录。
     * 
     * @return
     */
    @bean
    public docket createrestapi() {
        return new docket(documentationtype.swagger_2)
                .apiinfo(apiinfo())
                .select()
                .apis(requesthandlerselectors.basepackage("com.swaggertest.controller"))
                .paths(pathselectors.any())
                .build();
    }
    
    /**
     * 创建该api的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private apiinfo apiinfo() {
        return new apiinfobuilder()
                .title("spring boot中使用swagger2构建restful apis")
                .description("更多请关注http://www.baidu.com")
                .termsofserviceurl("http://www.baidu.com")
                .contact("sunf")
                .version("1.0")
                .build();
    }
}

模块化-starter

缘由

有开发过微服务的小伙伴应该体会过。当微服务模块多的情况下，每个模块都需要配置这样的一个类进行加载swagger。造成每个模块都存在大致一样的swaggerconfig,极端的情况下，有些朋友复制其他模块的swaggerconfig进行改造之后，发现仍然加载不出swagger的情况，造成明明是复制的，为何还加载不出，排查此bug及其费时间。

在此之上，可以构建出一个swagger-starter模块，只需要引用一个jar，加载一些特殊的配置，就可以快速的使用到swagger的部分功能了。

设计

创建模块swagger-spring-boot-starter。
功能大致如下：

1. 加载swaggerconfig。
2. 通过配置化配置swagger。
3. enable加载注解。

1. 创建swaggerconfig

swaggerconfig和之前的一致，只是里面的配置需要外部化。

@configuration
@propertysource(value = "classpath:swagger.properties", ignoreresourcenotfound = true, encoding = "utf-8")
@enableconfigurationproperties(swaggerproperties.class)
public class swaggerconfig {

  @resource
  private swaggerproperties swaggerproperties;

  @bean
  public docket builddocket() {
    return new docket(documentationtype.swagger_2)
        .apiinfo(buildapiinf())
        .select()
        .apis(requesthandlerselectors.basepackage(""))
        .paths(pathselectors.any())
        .build();
  }

  private apiinfo buildapiinf() {
    return new apiinfobuilder()
        .title(swaggerproperties.gettitle())
        .description(swaggerproperties.getdescription())
        .termsofserviceurl(swaggerproperties.gettermsofserviceurl())
        .contact(new contact("skyworth", swaggerproperties.gettermsofserviceurl(), ""))
        .version(swaggerproperties.getversion())
        .build();
  }
}

2. 创建swaggerproperties 配置相关

配置通过@propertysource注解加载resources目录下的swagger.properties。

创建swaggerproperties配置类,这个类里包含了一般swagger初始化要使用的一些常用的属性，如扫描包路径、title等等。

@data
@tostring
@configurationproperties(swaggerproperties.prefix)
public class swaggerproperties {

  public static final string prefix = "swagger";

  /**
   * 文档扫描包路径
   */
  private string basepackage = "";

  /**
   * title 如: 用户模块系统接口详情
   */
  private string title = "深兰云平台系统接口详情";

  /**
   * 服务文件介绍
   */
  private string description = "在线文档";

  /**
   * 服务条款网址
   */
  private string termsofserviceurl = "https://www.deepblueai.com/";

  /**
   * 版本
   */
  private string version = "v1.0";


}

做好这两件事情基本大工搞成了，为了更好的使用配置，在idea里和官方starter包一样，我们还需要配置一个additional-spring-configuration-metadata.json,让我们自己的配置也具有提示的功能，具体介绍请产考： 配置提示 ...

3. 加载swaggerconfig等特性

因为是starter模块，可能他人的项目目录和starter模块的目录不一致，导致加载不到swaggerconfig类，我们需要使用spring.factories把swaggerconfig类装载到spring容器。

resources/meta-inf

org.springframework.boot.autoconfigure.enableautoconfiguration=\
  io.purge.swagger.swaggerconfig

当然本次基于enable方式去加载swaggerconfig。

创建@enableswaggerplugins注解类，使用@import(swaggerconfig.class)将swaggerconfig导入大工搞成。

@retention(retentionpolicy.runtime)
@target(elementtype.type)
@import(swaggerconfig.class)
@enableswagger2
public @interface enableswaggerplugins {

}

使用

添加依赖

把自己编写好的swagger通过maven打包，自己项目引用。

<dependency>
  <groupid>com.purge.swagger</groupid>
  <artifactid>swagger-spring-boot-starter<factid>
  <version>0.1.0.release</version>
</dependency>

配置swagger.properties文件

• 在自己项目模块的resources目录下 创建swagger.properties配置

• swagger.properties 大致配置如下

swagger.basepackage="swagger扫描项目包路径"
swagger.title="swagger网页显示标题"
swagger.description="swagger网页显示介绍"

启动类添加@enableswaggerplugins注解。

@enableswaggerplugins
@springbootapplication
public class frontdemoapplication {

  public static void main(string[] args) {
    springapplication.run(frontdemoapplication.class, args);
  }

}

访问http://ip:端口/swagger-ui.html检查swagger-ui是否正常。

总结

简单的starter代码编写可以减少新模块的复杂性，只需要简单的配置就可以使用相应的特性，减少复制代码不必要的错误。

示例代码地址: