SpringBoot Swagger2 整合

swagger2 配置文件，在生产环境将 swagger.enable 设置为 false 即可关闭 swagger

@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable: true}")
public class SwaggerConfiguration {

  @Value("${swagger.basePackage:'com.magic.platform'}")
  private String basePackage;

  /**
   * buildDocket() 用于创建 Docket 的 Bean，
   * buildApiInfo() 创建 Api 的基本信息，用于显示在文档页面上。
   * select() 函数返回一个 `ApiSelectorBuilder` 实例，用来控制哪些接口暴露给 Swagger2 来展现。
   * 一般采用指定扫描的包路径来定义，本例中 Swagger 会扫描 controller 包下所有定义的API，
   * 并产生文档内容（除了被 @ApiIgnore 指定的请求）。
   * @return
   */
  @Bean
  public Docket buildDocket() {

    Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage(basePackage))
        .paths(PathSelectors.any())
        .build();

    return docket;
  }

  private Contact contact() {
    return new Contact("GrandKai","https://www.jianshu.com/u/9de0ad0f99bc", "GrandKai@aliyun.com");
  }

  private ApiInfo buildApiInfo() {
    return new ApiInfoBuilder()
        .title("Magic Platform APIS")
        .description("框架接口信息")
        .version("1.0.0")
        .contact(contact())
        .build();
  }
}

依赖配置-特别注意jar包冲突的问题

    <swagger.version>2.9.2</swagger.version>

      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
        <exclusions>
          <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-beans</artifactId>
          </exclusion>
        </exclusions>
      </dependency>
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
      </dependency>
...

页面查看接口 http://192.168.4.71:8081/swagger-ui.html

范例

/**
   * 根据 refreshToken 刷新 AccessToken
   * @param requestModel
   * @return
   */
  @ApiOperation(value = "刷新 accessToken", notes = "@param refreshToken")
  @ApiResponse(code = 200, message = "刷新 AccessToken 成功！")
  @PostMapping("refresh/token")
  public ResponseModel refreshToken(@RequestBody RequestModel<Void> requestModel) {

    Objects.requireNonNull(requestModel, "入参不能为空");

    TokenDTO tokenDTO = authenticationService.getRefreshToken(requestModel.getRefreshToken());

    return new ResponseModel<>("刷新 AccessToken 成功！", tokenDTO);
  }

使用 Spring Security 特别注意，需要将如下 url 加入白名单中，防止访问不到 swagger 接口页面

List<String> swaggerUrls = Arrays.asList("/v2/api-docs", "/csrf", "/**/*swagger*/**", "/error", "/");

参数说明：
说明：

@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面

• paramType：参数放在哪个地方
  -header-->请求参数的获取：@RequestHeader
  -query-->请求参数的获取：@RequestParam
  -path（用于restful接口）-->请求参数的获取：@PathVariable
  -body（不常用）
  -form（不常用）

• name：参数名

• dataType：参数类型

• required：参数是否必须传

• value：参数的意思

• defaultValue：参数的默认值

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

• code：数字，例如400
• message：信息，例如"请求参数没填好"
• response：抛出异常的类

@ApiModel：描述一个Model的信息（这种一般用在 post 创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候）

• @ApiModelProperty：描述一个model的属性