Spring Boot整合Swagger2的使用

一、Swagger2实战

1.1 pom文件添加Maven依赖

添加如下的依赖

		<!-- swagger2 配置 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.4.0</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.4.0</version>
		</dependency>

1.2 创建Swagger2配置类

package com.xinman.wristbandservice.config;

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.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @ClassName:  SwaggerConfig   
 * @Description:TODO(描述这个类的作用)   
 * @author: zhiguo.zheng
 * @date:   2020年2月27日 下午3:44:45
 */
@Configuration 
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xinman.wristbandservice.controller"))//填写你的controller所在的包名
                .paths(PathSelectors.any())
                .build();

    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("手环接口文档")
                .description("手环接口文档")
                .version("1.0")
                .build();
    }

}

1.3 controller中注解的使用

我们主要使用如下几个注解
@Api(tags = “xxxx”)：为整个controller添加一个注解
@ApiOperation(“xxxx”)：为某个请求添加注解
@ApiParam(“xxxx”)：为请求中的某个参数添加注解

package com.xinman.wristbandservice.controller;

import javax.servlet.http.HttpServletResponse;

import com.alibaba.fastjson.JSONObject;
import com.xinman.wristbandservice.utils.WristbandUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import com.xinman.wristbandservice.enums.ResponseEnums;
import com.xinman.wristbandservice.utils.BaseResponse;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * @Description:(描述这个类的作用)
 * @author: zhiguo.zheng
 * @date:   2020/10/13
 */
@RestController
@Api(tags = "手环")
@RequestMapping("/api/wristband/v1")
public class WristbandController {

    @ApiOperation("获取设备信息")
    @GetMapping("/info")
    public BaseResponse info(@RequestParam @ApiParam("imei编号") String imei) {
        JSONObject info = WristbandUtils.getInfo(imei);
        return new BaseResponse(ResponseEnums.OK.getStatus(), ResponseEnums.OK.getMsg(), info);
    }

    @ApiOperation("获取位置")
    @GetMapping("/location")
    public BaseResponse location(@RequestParam @ApiParam("imei编号") String imei) {
        JSONObject location = WristbandUtils.getLocation(imei);
        return new BaseResponse(ResponseEnums.OK.getStatus(), ResponseEnums.OK.getMsg(), location);
    }

    @ApiOperation("获取历史轨迹")
    @GetMapping("/track")
    public BaseResponse track(@RequestParam @ApiParam("imei编号") String imei,
                            @RequestParam @ApiParam("开始时间时间戳") Long beginTime,
                            @RequestParam @ApiParam("结束时间时间戳") Long endTime) {
        JSONObject track = WristbandUtils.getTrack(imei, beginTime, endTime);
        return new BaseResponse(ResponseEnums.OK.getStatus(), ResponseEnums.OK.getMsg(), track);
    }

    @ApiOperation("获取温度")
    @GetMapping("/temperature")
    public BaseResponse temperature(@RequestParam @ApiParam("imei编号") String imei) {
        JSONObject info = WristbandUtils.getTemperature(imei);
        return new BaseResponse(ResponseEnums.OK.getStatus(), ResponseEnums.OK.getMsg(), info);
    }

    @ApiOperation("获取心率和血压")
    @GetMapping("/hrAndBp")
    public BaseResponse hrAndBp(@RequestParam @ApiParam("imei编号") String imei) {
        JSONObject info = WristbandUtils.getHrAndBp(imei);
        return new BaseResponse(ResponseEnums.OK.getStatus(), ResponseEnums.OK.getMsg(), info);
    }

    @ApiOperation("演示ApiModel")
    @GetMapping("/test")
    public BaseResponse test(@RequestBody User user) {
        return new BaseResponse(ResponseEnums.OK.getStatus(), ResponseEnums.OK.getMsg(), user);
    }
}

1.4 实体类中注解的使用

@ApiModel(“xxxx”)：对整个实体类加注解
@ApiModelProperty(“xxxx”)：对实体类中的属性加注解

@ApiModel("用户信息")
@Data
public class UserInfo {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("密码")
    private String password;
    @ApiModelProperty("城市")
    private String city;
}

二、查看接口文档

访问地址：http://localhost:8401/swagger-ui.html
端口号根据自己的项目填写，我这里是8401换成你们自己的端口就好

选择一个具体的方法，可以看到我们对于请求参数配置的注解也是生效的

在下方models里面可以看到我们对UserInfo实体的注解详情

或者点击使用了UserInfo的方法然后选择model也可以看到我们的注解