Swagger学习指南

Swagger的优点

• 直接运行,可以在线测试API接口
• 在项目中使用Swagger需要Springbox

SpringBoot集成Swagger

• maven依赖,使用目前最新的3.0

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

• 引入依赖后,需要配置相关的config

在config包下的SwaggerConfig文件下
@Configuration
public class SwaggerConfig {
}

• 在Application中需要添加@EnableOpenApi
• 之后直接访问http://127.0.0.1:8080/swagger-ui/index.html#/

配置Swagger

• 配置一个bean实例,基于Docket

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2);
    }

• 需要使用的只需要配置一个title和description

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title( "Dr森的Swagger学习文档")
                .description("加油学习")
                .build();

    }

• 不要滥用RestController,会导致Swagger该Controller有全部的请求,最好是使用GetMapping,PostMapping等等

Swagger配置扫描接口

• Docket.select()

• 通过Docket.select().apis(RequestHandlerSelectors.basePackage(“com.example.swagger.controller”)),可以控制扫描哪个包下的Controller,但是不能说扫描具体哪一个controller,同一包下,通过@ApiIignore来屏蔽有的接口

• 扫描类上的注解,传入参数为注解的class例如GetMapping.class,只有类上有这个注解才会扫描到

• RequestHandlerSelectors.withClassAnnotation(GetMapping.class)

• 扫描方法上的注解,传入参数为注解的class例如GetMapping.class,只有某方法上有这个注解才会扫描到

• RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)

• 通过Docket.select.paths(PathSelectors.ant("/hello"))可以控制只扫描某个包下的接口

• 通过Docket.enable(false)可以关闭Swagger
  基于生产环境和现场环境,有不同的perpority,通过获取当前环境设置enable的值,然后保证现场无法使用Swagger

  public Docket docket(Environment enviroment){
      //设置要显示的Swagger环境
      Profiles profiles = Profiles.of("dev","test");
      //通过acceptProfile判断是否处在自己设定的环境当中
      boolean flag = enviroment.acceptsProfiles(profiles);
      通过flag判断是不是在dev或者test环境中
  }
  //环境的修改在properties文件中修改
  spring.profiles.active-dev
  

配置API文档的分组

• 同一个SwaggerConfig下是可以有多个Docket()的,每个都对应一个新的分组,设计到多人协作开发
• 通过.groupName()配置不同的分组名

Swagger文档的配置

• 如果实体类在Controller的返回值中,就会出现在Model中

• 使用@ApiModel,@ApiModelProperty

• 直接在controller方法中的参数前加上ApiParam("XXX")就可以在Swagger中看到参数的注释

常用注解：

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

参考 https://blog.csdn.net/u014231523/article/details/76522486