代码之家 › 专栏 › 技术社区 › OrwellHindenberg

在apiblueprint中记录请求负载

apiblueprint rest

0

OrwellHindenberg · 技术社区 · 9 年前

我有很多API端点需要记录,POST和PUT请求的有效负载可能很复杂。我正在用apiblueprint记录它们。我非常喜欢apiblueprint允许我记录URI参数的方式。它看起来很好,可以为读者提供他们所需的所有信息,例如(必需的、字符串或整数、列出选项/值并提供示例)。

然而,当我们查看请求部分时,我没有看到如何提供相同级别的原始文档。我看到的请求部分只是提供了一个示例请求。

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

页眉

内容类型:application/json

身体

{“id”:“123”}

请求主体应该如此稀疏吗?向我的用户传达REST有效负载的所有约束/要求的最佳方式是什么?

1 回复 | 直到 4 年前

1

Bishoy 9 年前

如果我理解正确,您正在寻找一种方法来记录您的请求参数(头、正文等)

如果是这种情况,那么使用Schema部分,并编写一个文档化的 JSON-Schema

例如,您当前的简单请求如下所示:

Request

    + Headers

        Content-Type: application/json

    + Schema

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

    + Body

    {"id":"123"}