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

你的名字 2022-09-12 11:48 859阅读 0赞

### 文章目录 ###

*  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;
      }
    }