[swagger]springboot结合swagger

本文适合第一次想亲手编写一个swagger的人看，这篇文章是我第一次学习时的笔记。
swagger官网：https://swagger.io/

1.创建一个springboot项目

file-》new-》project-》spring initializr -》直接下一步选择java8-》选择web ，spring web

2.添加swagger依赖

我pom中引用的是2.4.0版本

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>

3.添加swagger配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

@Configuration
@EnableSwagger2
public class swaggerConfig {

    //docket具体方法实现，然后加一系列东西，apiinfo自己实现，pathMapping配置访问路径
    //PathSelectors.regex("/.*") 正则匹配路径
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select()
                .paths(PathSelectors.regex("/.*"))
                .build();

    }
    private ApiInfo apiInfo(){
        //contact联系人
        return new ApiInfoBuilder()
                .title("我的接口")
                .contact(new Contact("wangyi","http://localhost:8868/mike/swagger-ui.html#/user-controller/queryUserInfoUsingPOST","loving9906@163.com"))
                .description("swagger的第一次使用")
                .version("1.0.0.0")
                .license("王一的csdn博客地址")
                .licenseUrl("http://localhost:8868/mike/swagger-ui.html#/user-controller/queryUserInfoUsingPOST")
                .build();
    }
}

配置完就可以尝试启动程序了，访问localhost:8080出现如下界面

4.增添swagger界面中方法的调用

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

import javax.servlet.http.HttpServletRequest;

@RestController
@RequestMapping(value = "/user")

public class MyMetheod {

    @GetMapping(value = "/get-token")
    @ApiOperation(value = "获取请求头中的token信息")
    public void getToken(
            @RequestHeader(value = "token",required = false) String token
    ) {
        // 直接获取 token 信息
        System.out.println("token = " + token);

        // 通过代码获取
        ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        if (servletRequestAttributes != null) {
            HttpServletRequest request = servletRequestAttributes.getRequest();
            String header = request.getHeader("token");
            System.err.println("header = " + header);
        }
    }
}

再次执行就有如下界面

5.swagger-ApiImplicitParams注释的使用

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;


/**
 * 加参数测试
 */
@RequestMapping(value = "/param")
@RestController
public class AddParam {
    @GetMapping(value = "/")
    @ApiOperation(value = "测试我的参数程序")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "startTime", value = "起始时间", dataType = "string", paramType = "query", required = false),
            @ApiImplicitParam(name = "endTime", value = "结束时间", dataType = "string", paramType = "query", required = false)
    })
    @ApiResponses({
            @ApiResponse(code = 100, message = "异常数据")
    })
    public void paratest(@RequestParam(required = false) String startTime,
                         @RequestParam(required = false) String endTime){
        System.out.println("开始时间："+startTime);
        System.out.println("结束时间："+endTime);
    }
}

控制台输出的结果

6.消除basic-error-controller : Basic Error Controller

                .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控

效果图

补充

application.yml文件可以修改端口号和访问时候的路径，默认端口是8080

swagger常用注释

@Api()：用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源
参数：

tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"

@ApiOperation()：用于方法，表示一个http请求访问该方法的操作
参数：

value="方法的用途和作用"    
notes="方法的注意事项和备注"    
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"} 
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

@ApiModel()：用于响应实体类上，用于说明实体作用
@ApiModelProperty：用在属性上，描述实体类的属性
@ApiImplicitParams：用在请求的方法上，包含多@ApiImplicitParam 用于方法，表示单独的请求参数
参数：

name="参数ming" 
value="参数说明" 
dataType="数据类型" 
paramType="query" 表示参数放在哪里
    · header 请求参数的获取：@RequestHeader
    · query   请求参数的获取：@RequestParam
    · path（用于restful接口） 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用） 
defaultValue="参数的默认值"
required="true" 表示参数是否必须传

@ApiParam()：用于方法，参数，字段说明 表示对参数的要求和说明
@ApiResponses：用于请求的方法上，根据响应码表示不同响应
@ApiResponse：用在请求的方法上，表示不同的响应
@ApiIgnore()：用于类或者方法上，不被显示在页面上
@Profile({“dev”, “test”})：用于配置类上，表示只对开发和测试环境有用