Search code examples
apiblueprintapiary.io

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


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

Solution

  • 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.