SpringBoot2.x与Swagger2的整合

一、导入坐标

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

二、编写Config配置类

package com.redisdemo.demo1.config;

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

/**
 * @Description:
 * @Author: ZhongPeng
 * @CreateTime: 2022-01-01  21:24
 */
@Configuration
@EnableSwagger2 //启用swagger2
public class Swagger2Config {

    /**
     * 用于配置Swagger2 包含文档基本信息
     * 指定swagger2的作用域(这里指定包路径下的所有API)
     * @return springfox.documentation.spring.web.plugins.Docket
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定需要扫描的controller路径
                .apis(RequestHandlerSelectors.basePackage("com.redisdemo.demo1"))
                //定义哪些路径上的接口需要生成文档
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 构建文档基本信息，用于页面显示
     * @return springfox.documentation.service.ApiInfo
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //标题
                .title("使用SpringBoot2与Swagger2进行整合构建的RestFul APIs")
                .description("通过访问swagger-ui.html,实现接口测试、文档生成")
                .termsOfServiceUrl("http://localhost:8080")
                //设置联系方式
                .contact(new Contact("zp","www.zp66.club","2442998721@qq.com"))
                .version("1.0")
                .build();
    }
}

三、编写测试接口

package com.redisdemo.demo1.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Description:
 * @Author: ZhongPeng
 * @CreateTime: 2022-01-01  21:39
 */
@Api(tags = "测试Swagger2模块")
@RestController
public class MyController {

    @GetMapping("/test")
    @ApiOperation(value = "测试1",notes = "测试11")
    @ApiParam(name = "msg",value = "信息",required = true,type = "string")
    public String hello(String msg){
        return msg;
    }
}

四、测试结果

五、对Swagger2中常用注解的讲解

1.@Api

tags：说明该类的作用，可以在UI界面上看到的注解
value：该controller简短的标题
description：详细介绍
producer：说明该controller是使用什么显示层格式的
protocols：使用什么协议

2.@ApiOperation

value：该方法的简述
note：详细介绍
code：正常情况下返回的状态码是多少
httpMethod：使用什么http方法
response：响应什么对象，这里写的是响应的对象的字节码

3.【@ApiImplicitParams】用在请求的方法上，表示一组参数说明

4.【@ApiImplicitParam】用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
dataType：参数类型，默认String，其它值dataType="Integer"       
defaultValue：参数的默认值
paramType：参数放在哪个地方
    · header --> 请求参数的获取：@RequestHeader
    · query --> 请求参数的获取：@RequestParam
    · path（用于restful接口）--> 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用）    

5.【@ApiModel】用于响应类上，表示一个返回响应数据的信息

6.【@ApiModelProperty】用在属性上，描述响应类的属性