Swagger 全局定义返回状态码和单独定义返回状态码

Posted 2021-10-16 简简单单OnlineZuozuo

文章目录

• Swagger 全局定义返回状态码和单独定义返回状态码
• • • • 1、单独使用注解定义
      • 2、定义全局的返回状态码

Swagger 全局定义返回状态码和单独定义返回状态码

---

1、单独使用注解定义

标准在接口方法上

@ApiResponses{
    @ApiResponse(code = 200 , message = "OK"),
    @ApiResponse(code = 401 , message = "Un")
}

2、定义全局的返回状态码

import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Slf4j
@EnableSwagger2
@Configuration
@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)
public class SwaggerConfig {

  @Value("${swagger.basePackage}")
  private String basePackage;


  /**
   创建API
   */
  @Bean
  public Docket createRestApi() {
    log.info(" Swagger Docket 加载");
    return new Docket(DocumentationType.SWAGGER_2)
      // 是否启用Swagger
      .enable(true)
      // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
      .apiInfo(apiInfo())
      // 设置哪些接口暴露给Swagger展示
      .select()
      // 扫描所有有注解的api，用这种方式更灵活
      .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
      // 扫描指定包中的swagger注解
      .apis(RequestHandlerSelectors.basePackage(basePackage))
      // 扫描所有 .apis(RequestHandlerSelectors.any())
      .paths(PathSelectors.any())
      .build()
      .useDefaultResponseMessages(false)
      .globalResponseMessage(RequestMethod.POST,responseMessageList())
      .globalResponseMessage(RequestMethod.GET,responseMessageList())
      // 这里可以继续增加更多的 RequestMethod
      ;
  }

  /**
   添加摘要信息
   */
  private ApiInfo apiInfo() {
    // 用ApiInfoBuilder进行定制
    return new ApiInfoBuilder()
      // 设置标题
      .title("标题：接口文档")
      // 描述
      .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
      // 作者信息
      .contact(new Contact("", null, null))
      // 版本
      .version("版本号:" + "").build();
  }

  private List<ResponseMessage> responseMessageList() {
    List<ResponseMessage> responseMessageList = new ArrayList<>();

    responseMessageList.add(new ResponseMessageBuilder().code(200).message("OK").build());
    responseMessageList.add(new ResponseMessageBuilder().code(201).message("Created").build());
    responseMessageList.add(new ResponseMessageBuilder().code(401).message("Unauthorized").build());
    responseMessageList.add(new ResponseMessageBuilder().code(403).message("Forbidden").build());
    responseMessageList.add(new ResponseMessageBuilder().code(404).message("Not Found").build());
    responseMessageList.add(new ResponseMessageBuilder().code(500).message("Error").build());

    return responseMessageList;
  }
}