SpringBoot（二） ---- SpringBoot集成Swagger

一、集成Swagger

　　1.添加Swagger依赖

　　　　这里使用了第三方UI，也可以使用官方UI：springfox-swagger-ui

   　　 <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.3</version>
        </dependency>

 

　　2.配置拦截器过滤Swagger地址

package com.toa.toabank.common.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * @Author neikou
 * @Date 2021/04/28
 **/
@Configuration
public class InterceptorConfig extends WebMvcConfigurationSupport {


    @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/");
        // 这是第三方的访问路径
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

    }

    /**
     * 可定义多个拦截器
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 定义过滤拦截的url名称，拦截所有请求
        super.addInterceptors(registry);
    }

}

 

　　3.创建Swagger配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    /**
     * 创建一个Docket对象 调用select()方法， 生成ApiSelectorBuilder对象实例，该对象负责定义外漏的API入口
     * 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate，在此我们使用any()方法，将所有API都通过Swagger进行文档管理
     * 访问地址/doc.html
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                //如果不想将所有的接口都通过swagger管理的话，可以将RequestHandlerSelectors.any()修改为RequestHandlerSelectors.basePackage()
                //.apis(RequestHandlerSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("com.bank.controller"))
                .paths(PathSelectors.any())
                .build();
    }
 
    @SuppressWarnings("deprecation")
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 标题
                .title("Server RESTful APIs")
                // 简介
                .description("这里是Server的所有接口信息")
                // 服务条款
                .termsOfServiceUrl("")
                // 作者信息
                .contact("neikou")
                // 版本
                .version("1.0").build();
    }

二、swagger注解配置说明

　　1.@Api：用在请求的类上，说明该类的作用

     　　　　tags="说明该类的作用"

     　　　　value="该参数没什么意义，所以不需要配置"

 

　　2.@ApiOperation：用在请求的方法上，说明方法的作用

　　　　　　httpMethod="请求方法：GET等"

　　　　　　value="说明方法的作用"

　　　　　　notes="方法的备注说明"

 

　　3.@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       

        　　　　name：参数名

　　      　　  value：参数的汉字说明、解释

      　　　　  required：参数是否必须传

　　　　　　dataType：参数类型，默认String，其它值dataType="Integer"      

      　　　　  defaultValue：参数的默认值

      　　　　  paramType：参数位于请求的位置
     　　       　　· header --> 获取方式：@RequestHeader
      　　   　　   · query --> 获取方式：@RequestParam
       　　  　　   · path--> 获取方式：@PathVariable
       　　 　　   · body获取方式：@RequestBody

 　　4.@ApiImplicitParams：用在请求的方法上，包含一组@ApiImplicitParam参数说明

　　　　　　@ApiImplicitParams({@ApiImplicitParam(),@ApiImplicitParam()})

 

　　5.@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

        code：数字，例如400

        message：信息，例如"请求参数没填好"

        response：抛出异常的类

 

　　6.@ApiResponses：用于请求的方法上,表示一组响应

 

　　7.@ApiModel：用于响应的实体类上，表示一个返回响应数据的信息
     

　　8.@ApiModelProperty：用在属性上，描述响应实体类的属性