Swagger 2.0版本定制化页面

最新推荐文章于 2025-06-27 16:55:21 发布

原创最新推荐文章于 2025-06-27 16:55:21 发布 · 921 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#swagger2

Swagger 模块专栏收录该内容

3 篇文章

订阅专栏

本文介绍了如何在Swagger2.0版本中实现响应页面的定制化，包括自定义响应状态码和响应模型。通过创建特定的响应类、配置Swagger配置文件以及在Controller中设置响应信息，可以全局或局部地调整SwaggerUI的展示。同时，提供了详细的代码示例和yaml文件以供参考。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

大家好，我是神韵，是一个技术&生活博主。出文章目的主要是两个，一是好记忆不如烂笔头，记录总结中提高自己。二是希望我的文章可以帮到大家。欢迎来点赞打卡，你们的行动将是我无限的动力。
本篇主题是：Swagger 2.0版本定制化页面

Swagger 2.0版本定制化页面

往往在开发过程中，可能会被要求定制化一下Swagger UI。在Swagger响应中，如果需要定制下面界面的状态码和响应model，需要简单去实现几步。(swagger3.0找了好久，定制化失败…）
在这里插入图片描述

实现步骤（所有代码看最后）
1、定制一个响应的类
在这里插入图片描述

2、在原本Swagger的配置文件新增一些配置，设置新的响应状态码并配置到全局变量中去
封装新的响应信息
在这里插入图片描述
将信息设置到全局变量中

3、在随意一个Controller设置一个响应Swagger，全部便会生效
在这里插入图片描述
注意
（1）、这里如果修改message信息，那么只有这个/date1接口的响应信息将会被修改成功，其他还是原来的
（2）、如果不配置全局信息，只配置.useDefaultResponseMessages(false)关闭默认响应，那么通过第三步也可以实现对单个Controller接口进行定制化，只是不会是全局，将会十分麻烦

ApiError.java

public class ApiError {
    private Integer code;

    private String responseDesc;

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getResponseDesc() {
        return responseDesc;
    }

    public void setResponseDesc(String responseDesc) {
        this.responseDesc = responseDesc;
    }
}

SwaggerConfig.java

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 不使用默认响应信息
                .useDefaultResponseMessages(false)
                // 为GET/POST请求设置定制化的响应信息
                .globalResponseMessage(RequestMethod.GET, getGlobalResponseMessage())
                .globalResponseMessage(RequestMethod.POST, getGlobalResponseMessage())
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("pers.xue.skills.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 设置swagger的一些信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("gather_all_single_function-Swagger2")
                .description("Restful API接口")
                .version("1.0.0")
                .build();
    }

    private List<ResponseMessage> getGlobalResponseMessage() {
        List<ResponseMessage> responseList = new ArrayList<>();
        responseList.add(new ResponseMessageBuilder().code(200).message("Successful").build());
        responseList.add(new ResponseMessageBuilder().code(400).message("Invalid request").responseModel(new ModelRef("ApiError")).build());
        responseList.add(new ResponseMessageBuilder().code(502).message("Server error").responseModel(new ModelRef("ApiError")).build());
        return responseList;
    }
}

SwaggerTestController.java

@RestController
public class SwaggerTestController {

    @PostMapping("/date1")
    @ApiResponses({
            @ApiResponse(code = 400, message = "Invalid request", response = ApiError.class)
    })
    public ResponseEntity<DateRspDTO> date(@RequestBody DateReqDTO dateReqDTO) {
        return new ResponseEntity<>(new DateRspDTO(), HttpStatus.OK);
    }
}

可以打开下面网站，将下面swagger.yaml复制进入看效果
https://editor.swagger.io/
swagger.yaml

swagger: '2.0'
info:
  description: Restful API接口
  version: 1.0.0
  title: gather_all_single_function-Swagger2
host: localhost:8082
basePath: /abs
tags:
  - name: swagger-test-controller
    description: Swagger Test Controller
paths:
  /date1:
    post:
      tags:
        - swagger-test-controller
      summary: date
      operationId: dateUsingPOST_1
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - in: body
          name: dateReqDTO
          description: dateReqDTO
          required: true
          schema:
            $ref: '#/definitions/DateReqDTO'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DateRspDTO'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/ApiError'
        '502':
          description: Server error
          schema:
            $ref: '#/definitions/ApiError'
definitions:
  ApiError:
    type: object
    properties:
      code:
        type: integer
        format: int32
      responseDesc:
        type: string
  DateReqDTO:
    type: object
    properties:
      creDateTime:
        type: string
        format: date-time
  DateRspDTO:
    type: object
    properties:
      creDateTime:
        type: string
        format: date-time

本文结束！