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

        response:抛出异常的类

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

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

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