Question

据我所知，没有办法在YAML的{key：value}对中的单个值上附加几个键。我是Swagger文档（OpenAPI 3.0）的新手，想知道是否可以将我的值组合在一起。例如，我搞砸了REST API文档，当我想列出一些响应而不每次都重写它时，我有以下内容：

paths:
  /users:
      post:
//some additional information here
        responses:
          '500':
//and for example here I want to add not only 201 status code but also others
                description: >-
                  Something went wrong on back end
//however I have to do something like this (writing them all)
          '502':
                description: >-
                  Something went wrong on back end
//and so on..

有什么最佳实践可以克服？也许从一开始我就有一个不好的观点。

Answer 1

您可以使用锚点和别名：

path:
  /users:
    responses:
      '500':
        description: &desc1 >-
          Something went wrong on back end
      '502':
        description: *desc1

Answer 2

OpenAPI 3.0支持的响应范围'1XX'-'5XX'可以用来代替单独列出代码：

    responses:
      '5XX':
        description: Something went wrong on back end

如果您仍然想单独列出响应代码，但是它们具有相同的description和schema，则可以$ref像这样的通用响应定义：

    responses:
      '501':
        $ref: '#/components/schemas/BackendErrorResponse'
      '502':
        $ref: '#/components/schemas/BackendErrorResponse'

components:
  responses:
    BackendErrorResponse:
      description: Something went wrong on back end
      content:
        application/json:
          schema:
            ...

OpenAPI规范存储库中还有一个增强请求，以允许reusing description across different responses。

如何为YAML对象中的几个键设置一个值

2 个答案: