【Demo】SpringBoot 整合Swagger2

1、应用环境

	jar包：1.8 以上
	pom 文件：
	<!-- swagger2  -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.8.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.8.0</version>
    </dependency>
		

2、目录结构

3、配置文件

package com.shane.blog.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;


/**
 * Swagger配置类
 * @author  shane.cx
 */
@Configuration
//启动Swagger2
@EnableSwagger2
//扫描需要的controller
@ComponentScan("com.shane.blog.controller")
//配置控制
@ConditionalOnProperty(prefix = "swagger2", value = {"enable"}, havingValue = "true")
public class SwaggerConfig {

    @Bean
    public Docket docker(){
        // 构造函数传入初始化规范，这是swagger2规范
        return new Docket(DocumentationType.SWAGGER_2)
                //apiInfo： 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含了第二部分的所有信息比如标题、描述、版本之类的，开发中一般都会自定义这些信息
                .apiInfo(apiInfo())
                // 分组信息
                .groupName("shane_group")
                //配置是否启用Swagger，如果是false，在浏览器将无法访问，默认是true
                //.enable(true) 已使用头部配置
                .select()
                //apis： 添加过滤条件,
                .apis(RequestHandlerSelectors.basePackage("com.shane.blog.controller"))
                //paths： 这里是控制哪些路径的api会被显示出来，比如下方的参数就是除了/user以外的其它路径都会生成api文档
                .paths((String a) ->
                        !a.equals("/user"))
                .build();
    }
    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                // 创建人信息
                .contact(new Contact("Shane.cx",  "https://blog.youkuaiyun.com/Shane_FZ_C/article/details/119868069",  "shane.cx@foxmail.com"))

                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述")
                .build();
    }
}

yml文件

#与 @ConditionalOnProperty配置对应
swagger2:
  enable: true

4、使用说明

package com.shane.blog.controller;


import io.swagger.annotations.*;
import lombok.Data;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;


/**
 * swagger2 注解说明
 * 1、用于controller类上
 * @Api  类说明
 *
 * 2、用于方法上面
 *@ApiOperation 方法的说明
 *@ApiImplicitParams、@ApiImplicitParam 方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明
 *
 * 3、用于方法上面（返回参数或对象的说明）
 * @ApiResponses、@ApiResponse	方法返回值的说明 ；@ApiResponses 用于指定单个参数的说明
 *
 * 4、对象类：
 * @ApiModel 用在JavaBean类上，说明JavaBean的 用途
 * @ApiModelProperty 用在JavaBean类的属性上面，说明此属性的的含议
 */


/**类说明
 * value url的路径值
 * tags	如果设置这个值、value的值会被覆盖
 * description	对api资源的描述
 * basePath	基本路径
 * position	如果配置多个Api 想改变显示的顺序位置
 * produces	如, “application/json, application/xml”
 * consumes	如, “application/json, application/xml”
 * protocols	协议类型，如: http, https, ws, wss.
 * authorizations	高级特性认证时配置
 * hidden	配置为true ，将在文档中隐藏
 * */

@Api(value = "权限管理",tags = "权限管理")
@RestController
public class AuthController {


    /**方法说明
     * @ApiOperation
     * value="说明方法的作用"
     * notes="方法的备注说明"
     */
    @ApiOperation(value="用户登录",notes="用户登录接口")
    /**
     * @ApiImplicitParam：对单个参数的说明
     *      name：参数名
     * 	    value：参数的说明、描述
     * 	    required：参数是否必须必填
     * 	    paramType：参数放在哪个地方
     * 	        · query --> 请求参数的获取：@RequestParam
     * 	        · header --> 请求参数的获取：@RequestHeader
     * 	        · path（用于restful接口）--> 请求参数的获取：@PathVariable
     * 	        · body（请求体）-->  @RequestBody User user
     * 	        · form（普通表单提交）
     * 	    dataType：参数类型，默认String，其它值dataType="Integer"
     * 	    defaultValue：参数的默认值
     */
    @ApiImplicitParams({
            @ApiImplicitParam(name="userName",value="用户名称",required=true,paramType="form"),
            @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
            @ApiImplicitParam(name="checkCode",value="验证码",required=true,paramType="form",dataType="Integer")
    })
    /**
     * @ApiResponses：方法返回对象的说明
     * @ApiResponse：每个参数的说明
     *    code：数字，例如400
     * 	  message：信息，例如"请求参数没填好"
     * 	  response：抛出异常的类
     */
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @ResponseBody
    @PostMapping(value = "/login")
    public ResultJson login(String userName,String password,String checkCode){
        ResultJson resultJson = new ResultJson();
        resultJson.setCode("0000");
        resultJson.setMessage("操作成功");
        return resultJson;

    }

}

/**
 * @ApiModel ：用于JavaBean上面
 * 当请求数据描述，即 @RequestBody 时， 用于封装请求（包括数据的各种校验）数据；
 * 当响应值是对象时，即 @ResponseBody 时，用于返回值对象的描述。
 */
@ApiModel(description = "返回结果")
@Data
class ResultJson{


    @ApiModelProperty(value = "返回码",required = true)
    private String code;

    @ApiModelProperty(value = "消息内容",required = true)
    private String message;

    @ApiModelProperty(value = "返回数据类型")
    private String data;

}

5、集成验证

yml文件

swagger2：
	enable： false

图示：

yml文件

swagger2：
	enable： true