apiaryio / api-blueprint

API Blueprint
https://apiblueprint.org
MIT License
8.65k stars 2.14k forks source link

How can I represent `array[object]` attributes? #383

Closed kyungmi closed 7 years ago

kyungmi commented 7 years ago

I want to write document like below. But It doesn't seem to be processed with Apiary editor in appropriate way.

+ Response 200 (application/json)

    Using `group_by` option

    + Attributes
        + result (array[object])
            + `book_id` (string) - book ID that is grouping annotations
            + `annotations` (array[Annotation]) - annotations in this book
        + `total_count` (number)

How do I write this kind of structure?

I attach screenshot of the preview window of Apiary Editor.

screenshot

kylef commented 7 years ago

You can't place key/value directory inside an array, you'd have to place it within an object as follows:

+ Response 200 (application/json)
    + Attributes
        + result (array[object])
            + (object)
                + `book_id` (string) - book ID that is grouping annotations
                + `annotations` (array[Annotation]) - annotations in this book
        + `total_count` (number)

## Data Structures
# Annotation (object)

+ some: thing

screen shot 2017-02-23 at 11 02 46

kyungmi commented 7 years ago

@kylef It is really helpful. Thank you so much :)