Azure API Management导入OpenAPI生成过长定义名的修改方法

通过Java注解生成openapi.json并导入Azure API Management后，200状态码的响应定义被自动生成为RestApiAdminLocationSourcesGet200ApplicationJsonResponse这类冗长名称。需要将该定义改为自定义名称，但无法修改返回类型（不能把数组包装到其他对象中），此前仅在LocationSourcePO类标记@Schema(name)并未生效。

生成的OpenAPI 3片段 #

"/rest/api/admin/locationSources": {
  "get": {
    "tags": [
      "Admin Location Source API"
    ],
    "summary": "Admin - Get all location sources",
    "description": "Get all location sources",
    "operationId": "getAllLocationSources",
    "responses": {
      "200": {
        "description": "Location sources retrieved successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/LocationSourceResponse"
              }
            }
          }
        }
      }
    }
  }
},
"LocationSourcePO": {
  "required": [
    "description",
    "locationSourceCode"
  ],
  "type": "object",
  "properties": {
    "locationSourceCode": {
      "maxLength": 2147483647,
      "minLength": 1,
      "type": "string",
      "description": "Location Source Code"
    },
    "description": {
      "maxLength": 2147483647,
      "minLength": 1,
      "type": "string",
      "description": "Location Source Code Description"
    }
  },
  "description": "Object for the Location Source PO."
}

原始Java代码 #

@GET
@Produces(MediaType.APPLICATION_JSON)
@Operation(
        summary = "Admin - Get all location sources",
        description = "Get all location sources for the Admin Console",
        responses = {
                @ApiResponse(responseCode = "200",
                        description = "Location sources retrieved successfully", content = @Content(array = @ArraySchema(schema = @Schema(implementation = LocationSourcePO.class)), mediaType = MediaType.APPLICATION_JSON))
        })
public Response getAllLocationSources() {
  List<LocationSourcePO> locationSourcePOs = locationSourceHandler.getAllLocationSource();

  return Response
         .ok()
         .entity(locationSourcePOs)
         .type(MediaType.APPLICATION_JSON)
         .build();
}

@Schema(name ="LocationSourcePO", description = "Object for the Location Source PO.")
public class LocationSourcePO {

@Schema(description = "Location Source Code")
private String locationSourceCode;

@Schema(description = "Location Source Code Description")
private String description;

// getter/setter省略
}

问题核心是返回的是数组类型，此前仅给单个元素的POJO命名无法覆盖OpenAPI生成器自动为数组响应生成的复合名称。需要直接在响应的Schema定义中为数组类型指定自定义名称，有两种写法：

写法1：直接使用@Schema定义数组并命名 #

修改@ApiResponse中的@Content配置，用@Schema(type = SchemaType.ARRAY)直接定义数组类型，并通过name属性指定自定义名称：

@GET
@Produces(MediaType.APPLICATION_JSON)
@Operation(
        summary = "Admin - 获取所有位置源",
        description = "为管理控制台获取所有位置源",
        responses = {
                @ApiResponse(responseCode = "200",
                        description = "位置源获取成功", 
                        content = @Content(
                            mediaType = MediaType.APPLICATION_JSON,
                            schema = @Schema(
                                type = SchemaType.ARRAY,
                                items = @Schema(implementation = LocationSourcePO.class),
                                name = "LocationSourcePOList" // 自定义数组响应名称
                            )
                        )
                )
        })
public Response getAllLocationSources() {
  List<LocationSourcePO> locationSourcePOs = locationSourceHandler.getAllLocationSource();

  return Response
         .ok()
         .entity(locationSourcePOs)
         .type(MediaType.APPLICATION_JSON)
         .build();
}

写法2：通过@ArraySchema指定名称 #

如果习惯使用@ArraySchema，可以在外层@Schema中指定名称：

@GET
@Produces(MediaType.APPLICATION_JSON)
@Operation(
        summary = "Admin - 获取所有位置源",
        description = "为管理控制台获取所有位置源",
        responses = {
                @ApiResponse(responseCode = "200",
                        description = "位置源获取成功", 
                        content = @Content(
                            mediaType = MediaType.APPLICATION_JSON,
                            array = @ArraySchema(
                                schema = @Schema(
                                    implementation = LocationSourcePO.class,
                                    name = "LocationSourcePOList" // 自定义数组响应名称
                                )
                            )
                        )
                )
        })
public Response getAllLocationSources() {
  // 方法逻辑不变
}

效果说明 #

修改后生成的openapi.json中，该数组类型会被注册到components/schemas下，名称为你指定的LocationSourcePOList，导入Azure API Management后就会使用这个简洁名称，不再生成冗长的自动命名。

内容的提问来源于stack exchange，提问作者petula