Question

我想使用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中的一个错误，因为在养蜂场它按照我的意图工作吗？谢谢！

Answer 1

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

Answer 2

您可以执行以下操作

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-value（字符串，必填） - 描述在上面的行“a” - ＆gt;属性名称，“a-value” - ＆gt;出现在正文中，“（字符串，必填）” - ＆gt;用于模式生成，“描述” - ＆gt;架构属性描述

混合请求/响应正文和数据结构

2 个答案: