springboot之swagger快速启动

springboot之swagger快速启动

简介

介绍

可能你们都有用过swagger,能够经过ui页面显示接口信息，快速和前端进行联调。

没有接触的小伙伴能够参考官网文章进行了解下demo页面。

多应用

固然在单个应用你们能够配置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.purgeteam</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代码编写能够减小新模块的复杂性，只须要简单的配置就可使用相应的特性，减小复制代码没必要要的错误。

示例代码地址: swagger-spring-boot