Rendering "attributes" section and Data Structures

[ghost]

Aglio looks fantastic but I have problems rendering complex cases as such:

I have this file: https://raw.githubusercontent.com/samwiseapi/apiary-samwise/master/apiary.apib

where I got a) "attributes" sections such as

 + Response 200 (application/json)
      + Attributes (SampleDTO)

b) custom Data Structures such as (note the SampleProperties which is itself a custom Data Structure)

 # Data Structures

 ## SampleDTO (object)
 + SampleId: 123456789 (number,  required)  - Sample ID
 + SampleProperties: SamplePropertiesDTO
 + ClientSampleId: 1 (number, optional) - Identifier of Sample ID received from client in request
 + Events (array[SamplePropertiesDTO], required) - Collection of sample events 

when I run the file agains aglio, these parts are ignored apparently. Would it be possible to add rendering to aglio for these?

apiary.io renders Attribute section as a table and does not have Data Structures and nested data structures render working but there are plans http://stackoverflow.com/questions/29848375/apiblueprint-structures-to-achieve-desired-description/29901429#29901429 - check here. I though like aglio design more.

[martnst]

+1 I just happened to miss the attributes as well.

[zdne]

Regarding Apiary.io – we are working on full rendering of attributes – MSON. This includes fully interactive ("foldable") tables and rendering of Named Types from Data Structure sections including Data Structures table of content.

[jolleon]

+1 I just started looking into Aglio part of evaluating various API testing and documentation solutions for my company and it looks great but the ability to reuse data structures is critical for my use case.

I'm particularly interested in seeing the Data Structure's "example" values rendered as the response body when the + Body section is missing. This would allow me to DRY my API Blueprint a lot by removing all the + Body sections. Dredd seems to already use the Data Structures + Attributes for response validation so removing the Body sections altogether would be fantastic to help keep documentation up to date.

Note that this is also the behavior suggested by the spec:

If defined, the Body section may be omitted and the example representation should be generated from the attributes description.

[danielgtaylor]

I'm working on adding support for attributes and data structures, as well as the generated body and schema from the attributes. This is a high priority item and is next on my todo list.

[jolleon]

Great to hear! How far along are you on this?

FWIW I quickly hacked together support for Attributes sections in my fork (see the updated example, look at the very last response the body is generated from the Attributes section).

It doesn't support "inheritance" or separate Data Structures. I may find time to work on this depending on whether you're already making progress on it or not.

If you're interested I can submit a pull request although this was the very first time I touched coffeescript and jade so the code may be terrible ;)

[whbath]

+1 Evaluating Blueprint/Apiary and Aglio but being able to document the semantics of the data structure is critical.

[danielgtaylor]

Please try installing via sudo npm install -g aglio@beta and give it a try. This will install the new theme engine branch, the new default theme and use drafter.js so that your attribute sections get rendered out as the body/schema in responses. I do still plan to render out the attribute sections themselves, but this beta release doesn't do much of that yet.

cc @onkami @maremmle @jolleon @whbath

[brandon-bethke-timu]

+1 I would also like to see this enhancement implemented.

[Anahkiasen]

:+1: for this, would really like this

[jonners99]

+1 This would be really useful

[aaronweatherall]

Hey mate, the beta branch works perfectly rendering the data, but I really need to be able to get collapsible and full-width.. the beta doesn't seem to support this?

[call-a3]

:+1: Looking forward to the upcoming release

[danielgtaylor]

Thanks for the feedback everyone. I've been out on vacation and am now back, so I'm planning to spend some time finishing up the beta and getting it into a stable release.

[danielgtaylor]

@aaronweatherall please try the latest 2.0.0-beta3 that I just released. It includes collapsible nav items and full-width support. The nav collapse feature is now built-in and automatic (based on window height) so there is no longer a commandline parameter to set. The full width option continues to require --theme-full-width but also supports --full-width for backward compatibility.

[robbinjanssen]

@danielgtaylor No sure if this is related to this issue, but it is related to the theme-branch / beta4 release and your nav update.

Using beta 4 the olio-theme causes too much load for the browser and makes it unresponsive. The problem is caused by: https://github.com/danielgtaylor/aglio/blob/olio-theme/templates/scripts.js#L150 https://github.com/danielgtaylor/aglio/blob/olio-theme/templates/scripts.js#L46-71

We have 13 resourceGroups with 8 actions inside each of them (I can send you the markdown privately for testing purposes if you want). For some reason the browser cannot handle the toggleCollapseNav call and stalls. Tested on OS X in latest Safari, Chrome and Firefox.

Since the last update the toggling of navs causes the browser to halt/hang.

[danielgtaylor]

@robbinjanssen intersting. I'd love to get an example blueprint to see the issue myself. It's possible that disabling the initial animation may help solve this issue. Feel free to email it to me via danielgtaylor@gmail.com.

[robbinjanssen]

@danielgtaylor check your mail :-) Again, if there's anything I can do to contribute. Let me know.

[danielgtaylor]

@robbinjanssen sorry about that, it was a bug that I introduced that prevented the page from loading. It is fixed here:

https://github.com/danielgtaylor/aglio/blob/olio-theme/templates/scripts.js#L120

When no good candidates are found to collapse, then we now collapse the largest, remove it from the candidate list and try again. I had run into this issue once before but thought it was a fluke with my browser. I wish I had tested this feature a bit better. Sorry about that! Expect a new release today.

[robbinjanssen]

Thanks!

edit: @danielgtaylor something might still be wrong with the rendering; could you elaborate why these groups are open? Same markdown is used as I emailed you.

[danielgtaylor]

@robbinjanssen it will now attempt to close as many groups as necessary to display everything on the page. That means some groups may stay open, and the groups it chooses are determined by their height. It will try to close the smallest possible group to fit everything on the screen. If nothing can be closed to fit everything, then the largest item is closed and it tries again, until either it runs out of items or fits everything.

If you make your window smaller and refresh the page, all items will get collapsed. If people have a very large screen, then they will see some of the items. The goal is to show as much as possible based on the window size at page load time.

[robbinjanssen]

@danielgtaylor that explains :) we're getting a bit offtopic here (maybe a separate issue?) but for the toggling i'd suggest that;

• Look at the currently selected item (#resource-group-action in the URL) and toggle that one open
• If nothing is selected and the items don't fit, toggle the first item(s) open until they no longer fit

Great work on the new engine btw! Can't wait to start developing my own themes :)

[danielgtaylor]

@robbinjanssen thanks! I've created #130 so let's continue this discussion there.

[ndonald2]

I've been playing with 2.0.0-beta6 and attribute support looks pretty awesome. My only request would be that the individual attribute details are rendered somewhere in a more human-readable way than just in the Schema section.

In other words, it would be nice to see something like:

Source:

# Data Structures

## User

+ id: 012345 (required, number) - Unique id of the user
+ name: Bob Smith (required, string) - Name of user

# Group Users

## User Info [/api/user/{user_id}]

### Get user info [GET]

+ Response 200 (application/json)

    + Attributes (User)

Result:

Users

USER INFO

[GET] /api/user/{user_id} Get User Info

Response 200

Headers

Content-Type: application/json

Attributes

id number (required) - Unique id of user name string (required) - Name of user

Body

{
    "id" : 012345,
    "name": "Bob Smith"
}

Schema

...etc...

[danielgtaylor]

@ndonald2 output like that is planned, but it is going to come after the 2.0 release. We are working on a simpler form of the MSON data representation and that will be used to support this feature. Even with the simplification MSON is quite complex (mixins, references, and deeply nested structures come to mind) so it will take a little time to get it right. First priority was making attributes get taken into account, next will be a better way of showing them.

[ndonald2]

Cool, thanks for the info! And thanks for the awesome project.

[loxy]

1+

[shumkov]

:+1:

[loxy]

The library renders also an JSON Schema, right? Is it possible to attach or rather specify something like a pattern (regex)? Don't found anything on this topic...

[benoittgt]

Hello

First thanks for Aglio, we love it. I just spent time to fix all blueprint errors in our code.

Like @ndonald2. Our customers are quite lost when they look into json schema to get POST object definitions. Having something like the Uri parameters should be awesome.

For example for the moment with :

+ Attributes
    + device (object)
        + blacklisted: "true" (boolean, required) - Blablabla

It returns

:open_mouth:

Are they an other existing way to do it ?

[danielgtaylor]

@benoittgt I am working on some related projects to try and make this possible in Aglio. We want to show something like the parameters for data structures, but it's a little more complicated. I promise it is something that we are taking very seriously and working on.

[benoittgt]

Thanks a lot @danielgtaylor

[mitsuruog]

:+1:

[robbinjanssen]

@danielgtaylor It might be worth checking out https://github.com/apiaryio/attributes-kit (Or has this been your plan all along? ;))

[danielgtaylor]

@robbinjanssen that has been the plan for a while, but was only publicly announced this week :wink:

I've been talking to the developers of Attributes Kit and there are a few important features we need to address before I can ship it in Aglio, but otherwise things are moving along nicely!

[ghost]

:+1: Thanks @danielgtaylor for your amazing work! Can't wait the next update with attributes rendering improvement as mentioned by @ndonald2 and @benoittgt !

[benoittgt]

Does the last update and specially attributes-kit help to resolve this ticket ? I don't how much each components speak to each other, and how they should help to resolve this issue.

Thanks @danielgtaylor

[danielgtaylor]

@benoittgt they do help! Attributes Kit is getting to the point where we can start using it in Aglio soon, but there are a few issues and open questions around theming to resolve first!

[Lambik]

+1 for this update, right now it's either "write full attributes" or "don't have the explanations in the data structures" (not using beta)

[pcowgill]

+1 for this update

[kocou-yTko]

+1

[ccasselman]

+1 for nested support

[danmux]

looking forward to this :+1:

[jcao02]

+1 waiting for this as well

[nrdsrfr]

+1

[benoittgt]

Please stop with the +1. We already know that lot's of people dream about this feature. Think about people that receive emails everytime with only this information.

[CumpsD]

Would this piece of blueprint also be helped with this issue, or does there exist a simple way in aglio today to list required input?

Pretty much just looking to output a simple table :)

### Create a domain [POST]

+ Request (application/json)

    + Attributes (object)
        + domain.name: example.com (string, required)

    + Body

            {
                "domain": {
                    "name": "example.com"
                }
            }

[benoittgt]

I see lot's of changes on attributes-kit. Does it mean some change on attributes on Aglio soon ? Thanks a lot

[countless-integers]

Yup, I'd love to see the api blueprint examples displaying correctly e.g. this one -- I only see schemas and no body examples when data structures are "inherited".

[bniwredyc]

Hey, guys, just in case, we made a fork with changes in template which show an attribute table based on schema. It looks like this:

package.json:

"devDependencies": {
    ...
    "aglio-theme-kaiten": "https://github.com/kaiten-hq/aglio-theme-kaiten.git#v1.6.7",
    ...
}

grunt-aglio config:

grunt.loadNpmTasks('grunt-aglio');
grunt.config('aglio', {
    api: {
        files: {
            ...
        },
        options: {
            theme: 'kaiten'
        }
    }
});

[kocou-yTko]

any news for this feature?