Swagger2构建在线RESTful API

简介：由于Spring Boot能够快速开发、便捷部署等特性，很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端（IOS、Android）或者Web前端。为了减少平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），需实时同步更新，除非有严格的管理机制，不然很容易导致不一致现象。
Swagger2可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

用途：Swagger是一个简单但功能强大的API表达工具，使用Swagger生成API，我们可以得到交互式文档

集成：引入依赖，配置Swagger，设置静态资源映射

使用：@ApiOperation，@ApiImplicitParams，@ApiImplicitParam注解

@ApiOperation:用在方法上，说明方法的作用

        Value：接口的名称

        Notes：描述

       Tags：在哪个分组下

        Response：描述接口的返回值（类，类型）

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在方法上，制定一个请求的各个方面

        Name:参数名，接口字段的名称

        Value：参数的意思

        DefaultValue：参数的默认值

        Required：参数是否是必须的

        dataType：参数类型

        paramType：参数放在那个地方，描述Post请求时

                Header-->请求参数获取：@RequestHesder

                query-->请求参数获取：@RequestParam

                Path（用于restful接口）-->@PathVariable

                Body-->@RequestBody 表示是一个json对象

                Form（表单提交）

下面介绍一下如何配置Swagger2

pom.xml

<!-- 加入Swagger2的依赖 -->
<!--在线文档-->
<!--swagger本身不支持spring mvc的，springfox把swagger包装了一下，让他可以支持springmvc-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

配置Bean

@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "guns",name = "swagger-open",havingValue = "true") //swagger开关
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.agesun.witness.api"))        //这里采用包扫描的方式来确定要现实的接口
                //.apis(RequestHandlerSelectors.withMethodAnnotation(TestController.class)      //这里采用包含注解的方式来确定要现实的接口
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("生成在线文档")
                .termsOfServiceUrl("http://172.16.20.237:8080/")
                .contact("wuyu")
                .version("1.0")
                .build();
    }
}

配置静态文件

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    if (config.getSwaggerOpen()) {//设置开关
        //MVC不能直接获取静态资源
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    super.addResourceHandlers(registry);
}

添加文件

在resource文件夹下建立文件META-INF  -->  spring-devtools.properties 文件里加入jar包

restart.include.beetl=/beetl-2.8.5.jar

配置文件config读取开关

@Component
@ConfigurationProperties(prefix = "guns")
public class Config {
    private Boolean swaggerOpen = false;
    public Boolean getSwaggerOpen() {      return swaggerOpen;    }
    public void setSwaggerOpen(Boolean swaggerOpen) {      this.swaggerOpen = swaggerOpen;    }
}

读取配置文件 .yml

guns:
  swagger-open: true  #是否开启swagger (true/false) (放在一个组内)

Controller使用配置

访问：http://IP:端口/swagger-ui.html

获取动态API