0

我想使用 aglio/api 蓝图为我们的新 API 创建一个很好的文档。

JSON 可能很大（有很多可选值），所以我想在正文中给出一个适当的用例，但也为 json 模式使用数据结构。但是，只要架构完全适合正文，生成的 HTML 就会向我抛出“Hello, world!”，因为我没有填写示例数据 - 但由于正文中有一个完整且有效的示例，我没想到 aglio 会创建 Hello World 输出。

作为参考，这就是我期望在生成的 htmls 正文中出现的内容：

{
    "a": "i want this to appear",
    "b": "in my aglio",
    "c": "html file"
}

这是实际出现的情况：

{
    "a": "Hello, world!",
    "b": "Hello, world!",
    "c": "Hello, world!",
    "d": "Hello, world!"
}

这就是原始的 api 蓝图：

FORMAT: 1A

# JSON Schema

# Test [/post/something]

## A Test [POST]

+ Request (application/json)
    + Attributes (SomeObject)

    + Body

        {
          "a": "i want this to appear",
          "b": "in my aglio",
          "c": "html file"
        }

+ Response 200

# Data Structures
## SomeObject (object)
+ a (string) - A
+ b (string) - B
+ c (string) - C
+ d (string, optional) - I'm optional, yet don't want to appear in the html, only the schema

那么，首先：这是一种有效的做事方式吗？你会推荐一种不同的方法吗？这是 aglio 中的错误吗，因为在 apiary 中它按我的意图工作？谢谢！

4

2 回答 2

0

找到了对应的github issue，看来我的描述没什么问题。 https://github.com/danielgtaylor/aglio/issues/221

于 2016-07-20T13:56:14.670 回答
0

您可以执行以下操作

FORMAT: 1A
# JSON Schema
# Test [/post/something]
JSON Schema Title
## A Test [POST]

+ Request (application/json)
    + Attributes (object)
        + a a-value (string, required) - description about a
        + b b-value (number, required) - description about b
        + c c-value (string, required) - description about c
        + d [a1, a2, a3] (array, optional) - I'm optional

+ Response 200 (application/json)
    {
     "message": "this works"
    }

a a-value (string, required) - 描述 在上面的行中 "a" --> 属性名称，"a-value" --> 出现在正文中，"(string, required)" --> 用于模式生成，"描述”-> 模式属性描述

于 2016-08-06T04:27:08.767 回答