3、swagger调试

Swagger：

1、将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；

2、当接口更新之后，只需要修改代码中的Swagger描述就可以实时生成新的接口文档了，从而规避了接口文档老旧不能使用的问题；

3、通过Swagger页面，可以直接进行接口调用，降低了项目开发阶段的调试成本（在线测试）

 

Swagger配置：

1、添加swagger相关依赖：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

2、Swagger的configuration配置：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean //配置docket以配置Swagger具体参数
    public Docket docket(Environment environment) {

        //动态配置项目所属什么环境时来显示swagger
        // 设置要显示swagger的环境
//        Profiles of = Profiles.of("dev", "test");

        // 判断当前是否处于该环境
        // 通过enable()方法接收此参数判断是否要显示
//        boolean flag = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                //配置文档页面信息
                .apiInfo(apiInfo())

                //动态配置是否启用Swagger，如果是false，在浏览器将无法访问
//                .enable(flag)

                //配置分组
                //配置多个分组只需要配置多个docket即可，不同docket有不同组名
                .groupName("组名")

                //构建Docket时通过select()方法扫描接口
                .select()


                //RequestHandlerSelectors：配置要扫描接口的方式
                    //1、扫描所有，项目中的所有接口都会被扫描到：any()
                    //2、不扫描接口：none()
                    //3、扫描方法上的注解：withMethodAnnotation（），
                            // 如withMethodAnnotation(GetMapping.class)只扫描get请求
                    //4、扫描类上的注解，参数是一个反射对象：withClassAnnotation（），
                            // 如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
                    //5、指定要扫描的包路径：basePackage(final String basePackage)
                //例：.apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                .apis(RequestHandlerSelectors.basePackage("控制类所在包名"))

                //配置如何通过path过滤,即这里只扫描请求以/controller开头的接口
                    //1、任何请求都扫描：any()
                    //2、任何请求都不扫描：none()
                    //3、通过正则表达式控制：regex(final String pathRegex)
                    //4、通过ant()控制：ant(final String antPattern)
                //例：.paths(PathSelectors.ant("/controller/**"))
                .paths(PathSelectors.ant("控制类中@RequestMapping中的路径"))
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger的学习笔记", // 标题
                "如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

    //配置分组一
    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }

    //配置分组二
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
}

3、测试访问：

http://localhost:8080/swagger-ui.html

 

Swagger常用注解：

1、@Api详解：

用于标注一个Controller

属性	描述
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

 

2、@ApiOperation详解：

用于对一个操作或HTTP方法进行描述

属性	描述
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
httpMethod	"GET","HEAD","POST","PUT","DELETE","OPTIONS"and"PATCH"
code	http的状态码 默认 200
extensions	扩展属性

3、@ApiParam详解：

用于请求方法中，定义api参数的注解

属性	描述
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

 

4、@ApiImplicitParams、@ApiImplicitParam详解：

（1）、@ApiImplicitParams：用在请求的方法上，包含一组参数说明

（2）、@ApiImplicitParam：对单个参数的说明

属性	描述
name	参数名
value	参数的说明、描述
required	参数是否必须必填
paramType	参数放在哪个地方  query --> 请求参数的获取：@RequestParam header --> 请求参数的获取：@RequestHeader path（用于restful接口）--> 请求参数的获取：@PathVariable body（请求体）--> @RequestBody User user form（普通表单提交）
dataType	参数类型，默认String，其它值dataType="Integer"
defaultValue	参数的默认值

5、@ApiModel、@ApiModelProperty详解：

（1）、@ApiModel：用于描述一个Model的信息

（2）、@ApiModelProperty：用来描述一个Model的属性。