---

一、配置步骤

1.在pom.xml中添加依赖

        <!--集成swagger2-->
        <!-- 生成api文档-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <artifactId>swagger-models</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <!-- 可视化接口 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
            <exclusions>
                <exclusion>
                    <artifactId>swagger-annotations</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
            </exclusions>
        </dependency>

2.创建Swagger2 的配置类

代码如下：

package com.platform.framework.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * @Description : Swagger2配置类
 * @Author : 冰雪伯爵
 * @Date : 2021/11/13
 * 访问地址
 * doc: 		http://localhost:8080/doc.html
 * Swagger: 	http://localhost:8080/swagger-ui.html
 **/
@Configuration        //配置类，项目启动的时候自动调用加载
@EnableSwagger2        //作用是自动开启swagger2
@Profile({"dev", "test"})     //作用域
//@EnableKnife4j
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        //添加head参数配置start
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("token").description("用户token").
                modelRef(new ModelRef("string")).
                parameterType("header").required(false).build();
        pars.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .apiInfo(apiInfo())        // 指定构建api文档的详细信息的方法：apiInfo()
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.platform.modules"))// 指定要生成api接口的包路径
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//使用了 @ApiOperation 注解的方法，才生成api接口文档
                .paths(PathSelectors.any())
                .build()    //可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .globalOperationParameters(pars);   //请求参数
    }

    /**
     * 设置api文档的详细信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 标题
                .title("Swagger2 快速开发平台接口文档")
                // 接口描述
                .description("swagger接口文档")
                // 联系方式
                .contact(new Contact("冰雪伯爵", "www.baidu.com", "test@gmail.com"))
                // 版本信息
                .version("1.0.0")
                // 构建
                .build();
    }
}

3. controller 测试

在controller中增加注解@API，方法上增加注解@ApiOperation，参数前加@ApiParam
代码如下：

@RestController
@RequestMapping(value = "/swagger")
@Api(tags = "测试swagger")
public class TestController {
    
    @PostMapping("/test")
    @ApiOperation(value = "swagger测试")
    public String test(@RequestParam("id") Integer id){
        return "swagger:"+id;
    }
}

4.Swagger2 常用注解说明

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：描述一个对象实体信息，即常用的实体、VO类、DTO类等描述

@ApiModelProperty()：用于描述对象实体的属性信息

@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解 自动生成接口忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：对单个参数的说明

@ApiImplicitParams：多个请求参数的说明

@ApiOperationSupport()：（knife4j增加特性）用于接口方法排序，作者信息描述等。

5.接口测试

启动项目，在浏览器地址栏输入访问地址，即可查看swagger文档

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