Swagger-core: 带有@Schema 的文档哈希图

创建于 2019-01-23 · 3评论 · 资料来源: swagger-api/swagger-core

你好，

如何描述使用 v2 注释返回Map<String, List<ComplexObject>>的 api 响应？还是Map<String, ComplexObject> ？

根据 OA3 模式，可以使用 additionalProperties 进行这样的建模：

openapi: "3.0.0"
info:
  title: Swagger Petstore
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /petGroups:
    get:
      operationId: listPetGroups
      tags:
        - pets
      responses:
        '200':
          description: Pets grouped by Ownername
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/MapResponse"


components:
  schemas:
    MapResponse:        # <---- dictionary<String,Array<Pet>>
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Pets'
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"

但是我看不到一种方法，如何在服务器端使用 java 注释来描述这种结构，因为@Schema没有additionalProperties 。

（最终目标是从服务器代码生成模式，或者至少验证服务器代码与上面的模式匹配）
谢谢

资料来源

yntelectual

👍9

最有用的评论

这样的事情会很棒：

content = @Content(map = @MapSchema(key = @Schema(implementation = String.class), value = @Schema(implementation = XXX.class)))

因此会在 swagger ui 中产生以下内容：

{
  "key": XXX > { ... }
}

ndtreviv 于 2020-09-03

👍4 😄1

所有3条评论

实现您想要的一种方法是让您的资源方法返回例如Map<String, List<Pet>>这将导致规范对上述内容作出响应：

        <strong i="7">@GET</strong>
        @Path("/path")
        public Map<String, List<Pet>> simpleGet(String data) {
            return null;
        }

更“侵入性”替代方案将被限定延伸的类例如HashMap<String, Pet>到中使用implementation的字段@Content内注释@Response ：

class MyModel extends HashMap<String, Pet> {}

@Operation(responses = {
  @ApiResponse(
    responseCode = "200",
    content = @Content(
      mediaType = "application/json", 
      schema = @Schema(implementation = MyModel.class)))
  }
)
<strong i="17">@GET</strong>
@Path("/path")
public Whatever simpleGet(String data) {
      return null;
}

frantuma 于 2019-02-04

😕1

似乎应该自动内省和应用某些东西，尤其是对于Map<String, XXX> - 不需要额外的语法。

clounie 于 2019-04-16