springboot项目整合swagger2

springBoot项目整合Swagger2

官方地址：https://swagger.io/

swagger版本号：2.9.2

springBoot 2.1.6

jdk 1.8

第一步：在pom.xml文件中引入jar包

      
        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        

       

第二步：配置swagger(Bean)

---

用 @Configuration 注解该类，等价于XML中配置beans；
用 @Bean 标注方法等价于XML中配置bean
不是不可以使用 xml，提倡使用注解

application.properties 中需要配置 swagger.enable=true 否则会被拦截，生产环境就不能配置

package cn.generate.config;

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.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 zycstart
 * @create 2020-05-27 21:18
 */
@Configuration
@EnableSwagger2
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class Swagger2Config {

    /**
     * 用于配置swagger2，包含文档基本信息
     * 指定swagger2的作用域（这里指定包路径下的所有API）
     *
     * @return Docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定需要扫描的controller
                .apis(RequestHandlerSelectors.basePackage("cn.generate.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 构建文档基本信息，用于页面显示，可以包含版本、
     * 联系人信息、服务地址、文档描述信息等
     *
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //标题
                .title("Spring Boot2中采用Swagger2构建RESTful APIs")
                .description("通过访问swagger-ui.html,实现接口测试、文档生成")
                //设置联系方式
                .contact(new Contact("番茄、薯条", "https://blog.csdn.net/m1234ilu/article/details/106392177", "[email protected]"))
                .version("1.0")
                .build();
    }

}

第三步：编写Controller

package cn.generate.controller;

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

import java.util.HashMap;
import java.util.Map;

/**
 * @author zycstart
 * @create 2020-05-27 21:50
 */
@RestController
@Api(tags = "测试接口")
@RequestMapping("/test")
public class TestController {
    private Map map = new HashMap<>();

    public TestController() {
        map.put(1, "张三");
        map.put(2, "李四");
        map.put(3, "王五");
        map.put(4, "赵六");
    }

    @ApiOperation(value = "查询用户集合",notes = "查询用户集合")
    @GetMapping("/listUsers")
    public Map getUsers(){
        return map;
    }
}

第四步：访问地址  localhost:8080/content-path/swagger-ui.html

swagger 提供的常用的注解有：

@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value 和 notes 的作用差不多，都是对请求进行说明；tags 则是对请求进行分类的，比如你有好几个 controller，分别属于不同的功能模块，那这里我们就可以使用 tags 来区分了。
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面。
@ApiResponses：用于表示一组响应
@ApiResponse：用在 @ApiResponses 中，一般用于表达一个错误的响应信息
@ApiModel：描述一个 Model 的信息（这种一般用在post创建的时候，使用
@RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候）表明这是一个被 swagger 框架管理的 model，用于class上
@ApiModelProperty： 这里顾名思义，描述一个 model 的属性，就是标注在被标注了 @ApiModel 的class的属性上，这里的 value 是对字段的描述，example 是取值例子，注意这里的 example很有用，对于前后端开发工程师理解文档起到了关键的作用，因为会在 api 文档页面上显示出这些取值来；这个注解还有一些字段取值，可以自己研究，举例说一个：position，表明字段在 model 中的顺序。

注意事项
一般swagger需要一下api的权限，需要在对应的模块进行排除
http://localhost:8080/swagger-resources/configuration/ui
http://localhost:8080/swagger-resources
http://localhost:8080/api-docs
http://localhost:8080/swagger-ui.html
http://localhost:8080/swagger-resources/configuration/security

如果项目使用了模板，例如freemaker，会导致访问swagger页面失败

解决方案：前后端分离，不适用模板；或者

@Configuration
public class WebMvcConfigurer extends WebMvcConfigurationSupport {

    /**
     * 发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。 需要重新指定静态资源
     *
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

————————————————
参考文章：https://blog.csdn.net/qq_40147863/article/details/88850053