springboot系列二：集成swagger2

pom依赖

<properties>
       <swagger2.version>2.7.0swagger2.version>
properties>


<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>${swagger2.version}version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>${swagger2.version}version>
dependency>

application.yml配置

swagger:
  enable: true

创建SwaggerConfig配置类

package com.yyl.system.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
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.ApiKey;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.SecurityScheme;
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;

/**
*
* @author  yangyile
* @since 2023-03-16 21:36
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger.enable}")
    private boolean swaggerEnable;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).enable(swaggerEnable).groupName("swagger")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yyl.system.controller"))
				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build().securitySchemes(unifiedAuth());
    }

//    头部配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Spring Boot中使用Swagger2构建RESTful APIs")
            .contact("yangyile")
          	.termsOfServiceUrl("https://blog.csdn.net/y2010081134")
            .version("1.0")
            .build();
    }

//    安全认证
    private static List<SecurityScheme> unifiedAuth() {
        List<SecurityScheme> arrayList = new ArrayList();
        arrayList.add(new ApiKey("token验证", "token", "header"));
        return arrayList;
    }
}

配置说明

@Configuration注解

表明该类是一个配置类，项目会自动引入swagger。

@EnableSwagger2注解

开启swagger。

@Value(“${swagger.enable}”)注解

指使用application.yml中swagger.enable的配置。

@Bean注解

注入spring容器，定制各个接口。

DocumentationType.SWAGGER_2

指定swagger版本类型。

enable方法

打开或者关闭swagger文档。

groupName方法

分组。

apiInfo方法

配置swagger的基本信息，如标题、作者、联系方式及版本等等。

select和apis方法

设置怎么扫描接口。RequestHandlerSelectors.basePackage(“com.yyl.system.controller”)表示只扫描controller包。RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)表示只对类上用@Api注解且方法上用@ApiOpearation的接口才会暴露给swagger。

paths方法

配置暴露给swagger的路由，PathSelectors.any()表示所有路由。也可以设置正则匹配。

securitySchemes方法

配置安全验证，这里设置token验证。

Controller使用示例

package com.yyl.system.controller;

import com.yyl.system.service.*;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.*;

@Api(tags = "系统用户")
@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    private IuserService userService;

    @ApiOperation(value = "获取用户列表", notes = "获取用户列表，支持分页和根据userName关键字查询")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "page", value = "", paramType = "query", dataType = "Integer"),
            @ApiImplicitParam(name = "limit", value = "", paramType = "query", dataType = "String"),
            @ApiImplicitParam(name = "userName", value = "用户名", paramType = "query", dataType = "String")
    })
    @GetMapping("/getUserList")
    public List<Map<String,Object>> getUserList() {
        return userService.getUserList();
    }
}

@Api注解

定义一个模块。应用在类前。

@ApiOperation注解

定义接口名称和描述。
@ApiOperation(value = “获取用户列表”, notes = “获取用户列表，支持分页和根据userName关键字查询”)。
value：定义接口名称；
notes：定义接口描述，接口的作用等等；

@ApiImplicitParams

定义方法参数。
@ApiImplicitParam(name = “userName”, value = “用户名”, paramType = “query”, dataType = “String”)。

@ApiImplicitParam主要有以下几种属性

• name：参数名；
• value：参数描述；
• required：是否必须；
• dataType：参数数据类型；
• paramType：参数类型；
• defaultValue：参数默认值；

paramType又分为以下几种类型

• header：标注为从@RequestHeader中获取；
• query：标注为从@RequestParam中获取；
• path：标注为@PathVariable中获取；

最终效果