Question

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

其中一个API调用具有include参数，允许用户指定要包含在响应中的其他字段
对于某些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 Blueprint Specification。

原始回答：

TL; DR：不支持，计划

据我所知，虽然您可以提供多个回复，但只有在响应代码或内容类型不同时才能这样做。

你的发现确实是正确的。目前无法做到这一点。我最近在思考这个想法。解决方案似乎解除了这个限制和实现隐式事务示例 - Automatic request response pairing。

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

（伪代码）：

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查询参数，此计划功能旁边还需要自动配对describing URI parameters values的语法。

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

1 个答案: