在apiblueprint中记录请求有效负载

Question

我有很多API端点要记录，POST和PUT请求的有效负载可能很复杂。我用apiblueprint记录它们。我非常喜欢apiblueprint允许我记录URI参数的方式。它看起来不错，让您为读者提供他们需要的所有信息，例如（必需，字符串或整数，列表选择/值并提供示例）。

当我们查看“请求”部分时，我没有看到如何提供相同级别的原始文档。我见过的请求部分只提供了一个示例请求。

假设我们正在处理一个简单的有效负载，它只需要一个名为id的整数。目前我的请求部分看起来像这样，

  

接头

     

Content-Type：application / json

     

体

     

{ “ID”： “123”}

请求体是否应该是稀疏的？向我的用户传达我的REST有效负载的所有约束/要求的最佳方法是什么？

Answer 1

如果我理解正确，您正在寻找一种方法来记录您的请求参数（标题，正文等）

如果是这种情况，那么使用Schema部分，并写一个记录良好的JSON-Schema

例如，您当前的简单请求将如下所示：

Request

    + Headers

        Content-Type: application/json

    + Schema

        {
            "type":"object",
            "properties":{
                "id": {
                    "type" : "string", 
                    "required": true
                }
            }
        }

    + Body

    {"id":"123"}