CODEWITHSUNDEEP
apiblueprintaglio
zaubara
zaubara

Reputation: 41

Mix Request/Response Body and Data Structures

I would like use aglio/api blueprint to create a nice documentation for our new API.

The JSON might be quite big (with lots of optional values), so I'd like to give a proper use case in the body, but also use data structures for the json schema. However, whenever the schema fits exactly the body, the resulting HTML throws "Hello, world!"s at me, since I didn't fill in the example data - but since I've got a complete and valid example in the body, I wouldn't have expected aglio to create Hello World output.

For reference, that's what I would expect in the resulting htmls body to appear:

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

This is what actually does appear:

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

And that's the raw api blueprint:

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

So, first: is that a valid way to do things? Would you recommend a different approach? Is this a bug in aglio, because in apiary it works as I intend it to? Thanks!

Upvotes: 0

Views: 310

Answers (2)

anjaneyulubatta505
anjaneyulubatta505

Reputation: 11665

You can do the following 

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) - description In above line "a" --> attribute name, "a-value" --> appears in body, "(string, required)" --> for schema generation, "description"--> schema attribute description

Upvotes: 0

zaubara
zaubara

Reputation: 41

Found the corresponding github issue, looks like nothing's wrong with my description. https://github.com/danielgtaylor/aglio/issues/221

Upvotes: 0

Related Questions