Api-blueprint: Bugs in rendering Attributes at Apiary.io

[jmdacruz]

When defining data structures which contain not only attributes, but also nested data structures, the "Attributes" table at Apiary.io does not show the nested data structures or attributes (it only displays the name of the top-level structure, with type "object")

For example:

• top_level_item1 (string) - A top level item
• top_level_item2 (string) - Another top level item
• properties (object) - A nested data structure
  
  
  
  • item1 (string) - A nested item
  
  
  • item2 (string) - Another nested item
  
  

Will display a table like this, which doesn't cover all of the MSON data model:

| Name | Type | Required | Description | Value |
| --- | --- | --- | --- | --- |
| top_level_item1 | string | | A top level item | |
| top_level_item2 | string | | A top level item | |
| properties | object | | A nested data structure | |

I would expect something like this (or similar):

| Name | Type | Required | Description | Value |
| --- | --- | --- | --- | --- |
| top_level_item1 | string | | A top level item | |
| top_level_item2 | string | | A top level item | |
| properties | object | | A nested data structure | |
| properties.item1 | string | | A nested item | |
| properties.item2 | string | | Another nested item | |

[hiBrianLee]

Seeing the same issue, thought I did something wrong. I wish it would show the data structure as well, as nothing under # Data Structures is shown on the page. I'd expect it to be under a separate header in the menu, probably called Data Structures (or Objects), in addition to Introduction, Reference.

It would also be beneficial to show the actual type in the attributes table, not object, which would be clickable I guess (which could just take it to the specific data structure page, or expand or something).

Here's an example blueprint.

# Group Foo

## FooContainer [/foo_container]

Returns `FooContainer`

+ Attributes (object)
    + description
    + foo (Foo)

# Data Structures

## Foo (object)
+ id
+ bar (Bar)

## Bar (object)
+ id
+ stuff

I'd expect the above blueprint to show something like below:

Group Foo

FooContainer [/foo_container]

Returns FooContainer

Attributes (object)

| Name | Type | Required | Description | Value |
| --- | --- | --- | --- | --- |
| description | | | | |
| foo | Foo | | | |
| foo {id} | | | | |
| foo {bar} | Bar | | | |
| foo {bar {id}} | | | | |
| foo {bar {stuff}} | | | | |

Data Structures

Foo (object)

| Name | Type | Required | Description | Value |
| --- | --- | --- | --- | --- |
| id | | | | |
| bar | Bar | | | |

Bar (object)

| Name | Type | Required | Description | Value |
| --- | --- | --- | --- | --- |
| id | | | | |
| stuff | | | | |

[hiBrianLee]

Btw, this isn't just an issue with Data Structures. Attributes table itself only handles first level attributes.

For example,

+ Attributes (object)
    + description
    + foo
        + id
        + name
        + price

The above will only show the following table:

| Name | Type | Required | Description | Value |
| --- | --- | --- | --- | --- |
| description | | | | |
| foo | | | | |

[zdne]

Hey @tigerpenguin @jmdacruz ,
at the moment the support of MSON in Apiary is in beta stage. We are working on nice, interactive (=foldable) and rich table as well as rendering Data Structure sections itself and the Table of Contents.

The current simple table is really sparse and basically acts as a placeholder.

Please bear with us as we working towards bringing the full, rich support for MSON in Apiary.

Thanks!

Related topics:

• https://github.com/apiaryio/api-blueprint/issues/25#issuecomment-94598413
• http://stackoverflow.com/questions/29848375/apiblueprint-structures-to-achieve-desired-description

[jmdacruz]

Thanks, @zdne!

[pete001]

+1

[foxx]

Quite excited to see what you guys have planned for this, it's a problem I've been trying to solve for a while now :)

[rcrooks]

@zdne I entered a help request around this - please ignore - I hadn't seen this thread. Good to see it's in the works!

[zdne]

:+1: I know guys are working on rendering this in Apiary documentation properly, please stay tuned.

Sneak peek (please note this is not the final version):

[foxx]

/me _drools_, that looks really nice

[jmdacruz]

That's very nice indeed!

[jakejgordon]

+1

[zdne]

@Baggz seems there is a lot of people interested in the progress of this in Apiary :smiley_cat:

[klevak]

+1 Major interest at @llbeaninc too. We need to do a better job describing our payloads and jsonSchema isn't exacly "designed for humans".

[acoulon99]

+1 From our group as well :)

[hiBrianLee]

Thanks @zdne. Can't wait till this gets shipped! Would parameters also support interactive rich tables for nested data playload as well? It would be awesome if it can!

[zdne]

Thanks @tigerpenguin! There is no plan for changing the parameters rendering at the moment. However in a future we want to converge these two so it will make sense to unify the rendering as well..

[anta]

+1 Can't wait to see Attributes section working and MSON support. Really nice feature!!

[mliberty]

+1

[JeroenVdb]

+1

[underyx]

+1, would be _so_ happy if this went live soon.

Any updates/estimated timeframes for release?

[zdne]

@underyx I will check the status out and keep you updated.

[zdne]

@underyx

The Apiary documentation has just been updated to match the visual style of Attributes:

However this has still the same functionality (e.g. no nested objects). I will share more on this tomorrow or the day after tomorrow.

[underyx]

@zdne Neat! Thanks for being so quick to respond!

[klevak]

@zdne noticing that the JSON Schema is also showing up now. But it's odd how it shows up above the actual response. In day or two will we see the nested attributes?

[zdne]

@klevak Hey Kris I will pass your remark on schema. This was just released so there maybe be still some changes.

In day or two will we see the nested attributes?

I wish I could promise this but it got unfortunately bumped by about two weeks due to importance of other things. Sorry about this :disappointed:

[JeroenVdb]

Is this issue related (and will it be fixed with this issue) to the issue we discovered and described here: https://github.com/apiaryio/drafter/issues/47 ?
Nested Objects aren't shown in the JSON view either.

[zdne]

@jakejgordon I believe this might be an unrelated bug – parhaps @pksunkara can clarify?

[pksunkara]

Yes, as I have mentioned in apiaryio/drafter#47, it is an unrelated bug.

[zdne]

Thanks for clarification @pksunkara !

[juniorleota]

Awesome, the description for the first level attributes is viewable today, looks great guys, +1

[foxx]

Hey @zdne, any update on when this functionality will be available?

[zdne]

@foxx unfortunately I do not have any new ETA to share at the moment. It is one of the top priorities but due to the importance of other things this was postponed :disappointed:

[jamesramsay]

This would be brilliant. I was beginning an experiment to move our docs to MSON and this would make my life much much better!

[klevak]

@zdne ... all eyes on this one. I think the anticipation might kill me.

[zdne]

I know Kris :/ please stay tuned we are doing what we can!

[alronlam]

Looking forward to the release of this feature! :D

[jk2K]

+1

[jamesramsay]

@zdne any update on this?

[zdne]

@jamesramsay between a react components and refracts nothing really. All available hands working on it.

[imZack]

+1 we are waiting for this :+1:

[zdne]

Note I've renamed this issue from "MSON: Nested data structures and attributes are not shown on "Attributes" table" – I hope this will make the scope of this issue more obvious (and thus prevents duplicates).

[alexzub]

+1, waiting for this too :+1:

[fernandosure]

+1 Please let me know once this is done, so i can update my docs :+1:

[jcieslar]

:+1: What's the status of this issue?

[cdel46]

+1 Anxiously pacing like an expectant father :+1:

[ghola]

+1

[randex]

+1
Why does it take so long?

[zdne]

@Randex we are taking this very seriously and working at the maximum to get this delivered. The MSON – as any other data description / schema – is very complex in its essence especially when you consider rendering deeply structures with multiple samples and mutually exclusive properties.

Please bear with as are we developing this – I believe you won't be disappointed.

[gigafied]

:+1:

[hims10]

:thumbsup:

[nickarnold]

:+1:

[admorphit]

:+1:

[zdne]

- message: Hello everyone, I have great news to share with you today! (string)

    Message for all the good folks at the [API Blueprint issue #191](https://github.com/apiaryio/api-blueprint/issues/191)

- author
    - name: Z
    - twitter: @zdne
    - address
        - company: `Apiary, INC`
        - street: 325 Ninth Street (required)
        - city: San Francisco
        - state: CA
        - zip (number, required)
        - tags: red, green, blue - Tags associated with this address

We have just released the attributes-kit – a library that renders MSON virtually anywhere. This library is the corner stone of MSON rendering in the Apiary. With it, we are getting really close to the proper support of MSON in Apiary. Note: This rendering is not available at Apiary just yet.

I would like to ask you to check out the attributes-kit playground at https://attributes-kit.herokuapp.com or use the it on your own and share with us any feedback, bug reports or comments you will find.

Check out the library at https://github.com/apiaryio/attributes-kit and let us know how you like it!

Big thank you for the waiting and your support. Let’s get the data modeling and visualization right together!

[pete001]

Yayyyy :+1:

[admorphit]

Cannot seem to get following

# Data Structures

## NewPerson
  - Include Person
  - address (string)

## Person (object, fixed)
  - first_name
  - last_name
  - address (object)

to display correctly in attributes-kit playground.

Thoughts?

Also noticed the screenshot posted with your MSON block is missing name and twitter fields?

[pksunkara]

@admorphit Unfortunately complete data structures support is not yet finished.

[mkuprionis]

:+1: Great news! Waiting eagerly:)

[vitorreis]

+1

[gigafied]

@zdne any update on this landing in Apiary?

[zdne]

@gigafied Apiary had to unfortunately slow down the works on this due to importance of other tasks. I would personally very much like to see this in January, hope it will work out. Sorry about the delay.

Meanwhile we have released a new version of parser that also renders JSON Schemas see here and here.

[toobulkeh]

:+1:

[o5]

@zdne Are you planning to show Members (enumeration of possible values) in Response / Attributes table?

I tried something like this:

FORMAT: 1A

# Test API

# TEST [GET /test/{id}]

+ Parameters
    + id (enum[string])

        Id of a Post

        + Members
            + `A` - This is character A
            + `B`
            + `C` - This is character C

+ Response 200 (application/json)

    + Attributes
        + id (enum[string])

            Id of a Post

            + Members
                + `A` - This is character A
                + `B`
                + `C` - This is character C

    + Body

            {
                "id": "A"
            }

and expected Possible values: A , B , C . also in Response / Attributes

Maybe I'm doing something wrong :)

Thanks.

EDIT: I missed SHOW JSON SCHEMA button but it would be great if Response / Attributes table looks like Request / Parameters table (or similar)

[zdne]

@o5 the answer is yes. We are also going to unify the rendering of URI parameters and body attributes in near future.

[Greyvend]

:+1: Waiting to see this feature on Apiary!

[CodeHex]

+1

[reingroot]

Looking forward to this feature! +1 :)

[ericpopivker]

is there a workaround for this using Blueprint Editor?

This is one feature that is blocking us from using apiary.io at this time.
It is really mandatory if you do documentation for anything but simplest flat API.

[Ross-Rawlins]

+1

[zrlay]

+1

[adparker]

@zdne Wondering if you guys can comment on this. Thanks!

[pksunkara]

Hey guys, We are working very hard on this currently. Please know that getting this out is our utmost priority. Please stay tuned. Thanks.

[podolinek]

+1

[netmilk]

Hey guys,

The improved rendering of Attributes in Apiary is going to be released very soon (days) and it's fixing a lot of issues mentioned above. I would love to roll it out to all of you first and I would love if you may provide some feedback if possible. If you're interested please reach out to our support when you logged into Apiary and we will flip the feature switch for you.

[groll75]

What ever happened to this?. I loved the preview thats was shown in the above thread by that was from last year and haven't seen this roll out yet.. waiting eagerly for this functionality.

[zdne]

Hey @groll75 Per Adam's comment above you can ask for access to the early version of the renderer at Apiary.

The latest development in the rendering component can be followed here: :https://github.com/apiaryio/attributes-kit/releases

[thomask]

+1

[paraskakis]

Hey everyone. The improved rendering has been released to 100% of the Apiary user base, so no need to ask us to flip the feature switch anymore! Hope you like it and please keep the feedback coming.

[paraskakis]

Conrad,

Please contact us on support [at] apiary.io and we'll help you out.

[ConradLang]

Looks like you need to edit your documentation and save before the new rendering is applied.

[emre-yildirim]

up 👍

[thangbxtonish]

Up (y)