我可以提供多个示例回复吗？

Question

我正在编写API的规范,其中响应中包含的字段各不相同.我希望能够提供多个示例来展示这一点.我的用例是:

1. 其中一个API调用具有一个include参数,允许用户指定要包含在响应中的一些其他字段
2. 对于某些API调用,响应中包含的字段取决于与用户API密钥关联的权限

我希望能做的是这样的:

+ Response 200 (application/json)

    {
      "id": 1, 
      "name": "Joe Bloggs",
      "email": "joe@example.com"
    }

+ Response 200 (application/json)

  If `include=telephone` was specified:

    {
      "id": 1, 
      "name": "Joe Bloggs",
      "email": "joe@example.com",
      "telephone": "0123456789"
    }

+ Response 200 (application/json)

  If the API key has access to address data:

    {
      "id": 1, 
      "name": "Joe Bloggs",
      "email": "joe@example.com",
      "address": [{
          "address1": "101 My street",
          "address2": "My area"
      }]
    }

据我所知,尽管您可以提供多个响应,但只有在响应代码或内容类型不同时才能这样做.有没有办法做到这一点？

Answer 1

更新:已经实现了这一点,请参阅API蓝图规范.

原始答案:

TL; DR:不支持,计划

据我所知,尽管您可以提供多个响应,但只有在响应代码或内容类型不同时才能这样做.

你的发现确实是正确的.目前无法做到这一点.我最近在思考这个想法.解决方案似乎解除了这个限制并实现了隐式事务示例 - 自动请求响应配对.

请注意,在您的情况下,这似乎是基于请求的两个不同的事务示例

(伪):

Example 1: 
- Request With Phone Number
- Response With Phone Number 200 (application/json)

Example 2: 
- Request Default
- Response Default 200 (application/json)

假设include=telephone是URI查询参数,此计划特征将在自动配对旁边还需要用于描述URI参数值的语法.