springboot整合swagger2&springboot2.6.5以上版本整合swagger3

---springboot整合swagger2---

　　swagger是一个不错的接口生成工具，而且其UI界面可以查看以及测试接口。

　　之前前后端分离的时候是将文档写在docx中，然后自己测试用postman进行测试。确实比较浪费时间。

1.简单的整合

0.pom新增

        <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>

 

1.增加配置文件：

package com.zd.bx.config.swapper2;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

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;

@Configuration
@EnableSwagger2
// 是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class Swagger2Configure implements WebMvcConfigurer {

    // swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.zd.bx.controller")).paths(PathSelectors.any()).build();
    }

    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("XXX软件接口描述")
                // 创建人信息
                .contact(new Contact("张三", "https://www.baidu.com/", "zhangsan@qq.com"))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述").build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

2.application.properties激活swagger2

#是否激活 swagger true or false
swagger.enable=true

如果有拦截器或者权限过滤器需要放行swagger相关请求：

例如我的shiro权限配置如下：

        FILTER_CHAIN_DEFINITION_MAP.put("/swagger-ui.html", "anon"); // swagger放开
        FILTER_CHAIN_DEFINITION_MAP.put("/webjars/**", "anon"); // swagger请求的资源放开
        FILTER_CHAIN_DEFINITION_MAP.put("/swagger-resources/**", "anon"); // swagger请求的资源放开
        FILTER_CHAIN_DEFINITION_MAP.put("/v2/api-docs/**", "anon"); // swagger请求的资源放开

 3. 启动应用访问：

2.注解使用

1.@Api  修饰类

// tags:说明该类的作用，可以在UI界面上看到的注解,value=该参数没什么意义、在UI界面上也看到
@Api(tags = { "用户接口" })
public class UserController extends AbstractController<User, Long> {

如下：

2.@ApiOperation 方法描述

3.@ApiResponses、@ApiResponse修饰返回值信息

4.@ApiImplicitParam 参数描述

5.@ApiModel、@ApiModelProperty  修饰请求的参数和返回参数的信息(用于JSON请求参数和返回值)

例如：

    @GetMapping("/detail/{id}")
    // 方法描述
    @ApiOperation(value = "详情", notes = "查询详情")
    // 返回信息描述
    @ApiResponses({ @ApiResponse(code = -1, message = "请求正确") })
    // 参数描述
    @ApiImplicitParam(name = "id", value = "请求的ID", required = true)
    public JSONResultUtil<T> detail(@PathVariable() E id, HttpServletRequest request) {
        T bean = getBaseService().selectById(id);
        ValidateUtils.isTrue(bean != null, "u100003");

        return JSONResultUtil.successWithMsgAndData("ok", bean);
    }

结果：

 

 

 3. 如果希望在用UI请求的时候携带参数，比如cookie、header等参数

package com.zd.bx.config.swapper2;

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

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import com.zd.bx.utils.constant.DefaultValue;

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;

@Configuration
@EnableSwagger2
// 是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class Swagger2Configure implements WebMvcConfigurer {

    // swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        // 增加请求头配置
        ParameterBuilder params = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        // 设置参数的名字以及类型：可以是cookie、header等信息
        Parameter access_token = new ParameterBuilder().name(DefaultValue.TOKEN_KEY).description("access_token")
                .modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        Parameter belong_database = new ParameterBuilder().name(DefaultValue.DATABASE_NAME_KEY)
                .description("belong_database").modelRef(new ModelRef("string")).parameterType("header").required(false)
                .build();
        pars.add(access_token);
        pars.add(belong_database);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.zd.bx.controller")).paths(PathSelectors.any()).build()
                .globalOperationParameters(pars);

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("XXX软件接口描述")
                // 创建人信息
                .contact(new Contact("张三", "https://www.baidu.com/", "zhangsan@qq.com"))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述").build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

结果：

 

补充：swagger2生成所有类型的请求文档，如下：

 原因是我们没有指定请求方式，也就是 @RequestMapping 没有指定methos。解决办法：直接用@PostMapping或者指定method。

 

 补充：swagger2也可以对指定的包或者包含某注解的类进行生成API

    @Bean
    public Docket createRestApi() {
        // 增加请求头配置
        ParameterBuilder params = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        // 设置参数的名字以及类型：可以是cookie、header等信息
        Parameter access_token = new ParameterBuilder().name(DefaultValue.TOKEN_KEY).description("access_token")
                .modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        Parameter belong_database = new ParameterBuilder().name(DefaultValue.DATABASE_NAME_KEY)
                .description("belong_database").modelRef(new ModelRef("string")).parameterType("header").required(false)
                .build();
        pars.add(access_token);
        pars.add(belong_database);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 为任何接口生成API文档
                .apis(RequestHandlerSelectors.any())
                // 指定包生成API文档
                // .apis(RequestHandlerSelectors.basePackage("com.zd.bx.controller"))
                // 为有@ApiOperation注解的方法生成API文档
                // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 为有@Api注解的Controller生成API文档
                // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any()).build().globalOperationParameters(pars);
    }

补充： @ApiIgnore用于忽略参数

    @GetMapping("test")
    public String test(@ApiIgnore String param1, @RequestParam("param2") String param2) {
        return param2;
    }

结果：

补充：swagger也可以分组。这个在一个项目中Controller特别多的时候比较有用。 

package com.xm.ggn.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;

/**
 * @Author: qlq
 * @Description
 * @Date: 17:10 2021/1/30
 */
@Configuration
@EnableSwagger2
// 是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
// 按环境区分
//@Profile("dev")
public class Swagger2Configure implements WebMvcConfigurer {

    //根据包进行分组
    @Bean
    public Docket createCommonApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.xm.ggn.controller.common")).paths(PathSelectors.any()).build().groupName("common 基础服务");
    }

    // swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createUserApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.xm.ggn.controller.user")).paths(PathSelectors.any()).build().groupName("user 服务");
    }

    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("XXX软件接口描述")
                // 创建人信息
                .contact(new Contact("张三", "https://www.baidu.com/", "zhangsan@qq.com"))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述").build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

结果：

补充：如下一个接口 

1. 相关Bean

package cn.xm.controller;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.util.List;

@Data
@ApiModel("请求实体")
public class RequestVO {

    @ApiModelProperty("序列号req")
    private String sequenceNum;

    @ApiModelProperty("用户集合req")
    private List<UserVO> userVOS;

    @Data
    @ApiModel("UserVO请求实体")
    public static class UserVO {

        @ApiModelProperty("用户名req")
        private String username;
    }
}

Response：

package cn.xm.controller;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.util.List;

@Data
@ApiModel("返回实体")
public class ResponseVO {

    @ApiModelProperty("序列号")
    private String sequenceNum;

    @ApiModelProperty("用户集合")
    private List<UserVO> userVOS;

    @Data
    @ApiModel("UserVO返回实体")
    public static class UserVO {

        @ApiModelProperty("用户名")
        private String username;
    }
}

2. Controller

package cn.xm.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import springfox.documentation.annotations.ApiIgnore;

@RequestMapping("test2")
@Controller("testController2")
@Api(tags = "测试接口")
public class TestController {

    @PostMapping("/testSwagger")
    @ApiOperation("测试swagger接口方法")
    public ResponseVO test(@RequestBody @ApiParam("请求参数") RequestVO requestVO, @ApiParam("请求参数2") String param2, @ApiIgnore String param3) {
        return new ResponseVO();
    }


    @PostMapping("/test2")
    @ApiOperation("测试swagger接口方法")
    @ResponseBody
    public ResponseVO2 test2(@RequestBody @ApiParam("请求参数") ResponseVO2 responseVO2) {
        System.out.println(responseVO2);
        return responseVO2;
    }

}

其test方法生成的Swagger如下：

---springboot2.6.5以上版本整合swagger3 ---

1. pom

<!-- Swagger3 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

2. 配置增加

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

 3. 增加自动配置类：

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@ConditionalOnProperty(name = "springfox.documentation.enabled", havingValue = "true")
@EnableOpenApi
public class Swagger2Configure {

    /**
     * 组名。默认取服务名称
     */
    @Value("${spring.application.name:xxxxx}")
    private String groupName;

    // swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(groupName)
                .apiInfo(apiInfo()).select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("x.xx.xxx"))
                .paths(PathSelectors.any()).build();
    }

    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title(groupName + "接口描述")
                // 创建人信息
                .contact(new Contact("xxx", "https://www.baidu.com/", "zhangsan@qq.com"))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述").build();
    }


}

　　springfox.documentation.enabled 该值默认是true， 自动配置就已经注入该配置了。并且配置中也是用该配置判断的是否开启。也就是该类也可以不需要，添加上的效果就是修改默认的Docket。

　　如果想线上关闭swagger， 直接将springfox.documentation.enabled 配置为false。

4. 测试

/swagger-ui/index.html