How do I get Apiary model details from the rendered documentation?

Question

I have an API contract defined in Apiary and I'm using the Resource model syntax to enable reuse of payloads.

The documentation rendered by Apiary only shows the model name though (eg Response 200 returns a [Foo][]) - without any further details on what Foo is, or any link to view the attributes in the Foo model.

Given a model, how do I see what its attributes are in the rendered documentation?

update
The relevant part of the contract is below:

### Manipulating a specific Organisation [/organisations/{id}]
Operations to retrieve and update a specific Organisation.

+ Parameters

    + id (required, guid, `F339ADA5-E836-40FE-8E90-BEF06892762E`) ... The guid Organisation `id`.

+ Model (application/json)

    + Headers

            Link : <http://foobar.com/organisations/F339ADA5-E836-40FE-8E90-BEF06892762E>;rel="self"

    + Body

            {
                "id" : "F339ADA5-E836-40FE-8E90-BEF06892762E",
                "name" : "joe's gardening supplies"
            }

### Retrieve an Organisation [GET]

+ Response 200

        [Organisation][]

### Update an Organisation [PATCH]

+ Request

        [Organisation][]

+ Response 204

score 3 · Accepted Answer · answered Jun 23 '14 at 07:51

Unless you provide an example, it's just guessing, but my first guess would be wrong level of indentation. How example blueprint could look like:

FORMAT: 1A
HOST: http://www.google.com

# Model Example
Notes API is a *short texts saving* service similar to its physical paper presence on your table.

# Group Notes
Notes related resources of the **Notes API**

## Note [/notes/{id}]
A single Note object with all its details

+ Parameters
    + id (required, number, `1`) ... Numeric `id` of the Note to perform action with. Has example value.

+ Model

    + Header

            X-My-Header: The Value

    + Body

            { "id": 2, "title": "Pick-up posters from post-office" }

### Retrieve a Note [GET]
+ Response 200 (application/json)

    [Note][]

### Remove a Note [DELETE]
+ Response 204

Code above results in this documentation, where model is correctly incorporated on places where it's referenced (and where such reference is supported - i.e. definition of payload).

Sometimes it's helpful to read the raw version of Apiary's docs on GitHub, because it's easier to spot the right, exact format that way.

cheers - i've updated the question with my example. it looks very similar to your example so I'm not sure why it doesn't work. — Justin, Jun 24 '14 at 01:57

score 1 · Answer 2 · answered Jun 24 '14 at 03:08

1

ok, from comparing the two examples I've worked it out.

in my contract the model reference

[Organisation][]

was indented two tabs instead of one. :S

that's a really easy mistake to make - would be helpful if Apiary flagged the incorrect indentation level for a model reference.

answered Jun 24 '14 at 03:08

Justin

227
2
8

Yes this is planned https://github.com/apiaryio/snowcrash/issues/38, sorry about this. Technical detail: two tabs are making it a code block – an opaque asset – parser threats it as a message-payload body – Zdenek Jun 24 '14 at 16:51

How do I get Apiary model details from the rendered documentation?

2 Answers2