New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rendering "attributes" section and Data Structures #103

Open
onkami opened this Issue Apr 28, 2015 · 77 comments

Comments

Projects
None yet
@onkami

onkami commented Apr 28, 2015

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

This comment has been minimized.

Show comment
Hide comment
@martnst

martnst Apr 28, 2015

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

martnst commented Apr 28, 2015

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

@zdne

This comment has been minimized.

Show comment
Hide comment
@zdne

zdne Apr 28, 2015

Collaborator

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.

Collaborator

zdne commented Apr 28, 2015

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

This comment has been minimized.

Show comment
Hide comment
@jolleon

jolleon Apr 29, 2015

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

jolleon commented Apr 29, 2015

+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

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor May 6, 2015

Owner

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.

Owner

danielgtaylor commented May 6, 2015

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

This comment has been minimized.

Show comment
Hide comment
@jolleon

jolleon May 11, 2015

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 ;)

jolleon commented May 11, 2015

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

This comment has been minimized.

Show comment
Hide comment
@whbath

whbath May 25, 2015

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

whbath commented May 25, 2015

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

@danielgtaylor danielgtaylor changed the title from Rendeing "attributes" section and Data Structures to Rendering "attributes" section and Data Structures May 27, 2015

@danielgtaylor

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor May 28, 2015

Owner

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

Owner

danielgtaylor commented May 28, 2015

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-neudesic

This comment has been minimized.

Show comment
Hide comment
@brandon-bethke-neudesic

brandon-bethke-neudesic Jun 11, 2015

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

brandon-bethke-neudesic commented Jun 11, 2015

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

@Anahkiasen

This comment has been minimized.

Show comment
Hide comment
@Anahkiasen

Anahkiasen Jun 25, 2015

👍 for this, would really like this

Anahkiasen commented Jun 25, 2015

👍 for this, would really like this

@jonners99

This comment has been minimized.

Show comment
Hide comment
@jonners99

jonners99 Jun 29, 2015

+1 This would be really useful

jonners99 commented Jun 29, 2015

+1 This would be really useful

@aaronweatherall

This comment has been minimized.

Show comment
Hide comment
@aaronweatherall

aaronweatherall Jul 1, 2015

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?

aaronweatherall commented Jul 1, 2015

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

This comment has been minimized.

Show comment
Hide comment
@call-a3

call-a3 Jul 7, 2015

👍 Looking forward to the upcoming release

call-a3 commented Jul 7, 2015

👍 Looking forward to the upcoming release

@danielgtaylor

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor Jul 7, 2015

Owner

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.

Owner

danielgtaylor commented Jul 7, 2015

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

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor Jul 9, 2015

Owner

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

Owner

danielgtaylor commented Jul 9, 2015

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

@danielgtaylor danielgtaylor added this to the Aglio 2.0 milestone Jul 10, 2015

@robbinjanssen

This comment has been minimized.

Show comment
Hide comment
@robbinjanssen

robbinjanssen Jul 13, 2015

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

robbinjanssen commented Jul 13, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor Jul 13, 2015

Owner

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

Owner

danielgtaylor commented Jul 13, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@robbinjanssen

robbinjanssen Jul 13, 2015

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

robbinjanssen commented Jul 13, 2015

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

@danielgtaylor

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor Jul 13, 2015

Owner

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

Owner

danielgtaylor commented Jul 13, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@robbinjanssen

robbinjanssen Jul 13, 2015

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.

robbinjanssen commented Jul 13, 2015

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

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor Jul 15, 2015

Owner

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

Owner

danielgtaylor commented Jul 15, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@robbinjanssen

robbinjanssen Jul 15, 2015

@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 :)

robbinjanssen commented Jul 15, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor Jul 15, 2015

Owner

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

Owner

danielgtaylor commented Jul 15, 2015

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

@ndonald2

This comment has been minimized.

Show comment
Hide comment
@ndonald2

ndonald2 Jul 15, 2015

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

ndonald2 commented Jul 15, 2015

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

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor Jul 16, 2015

Owner

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

Owner

danielgtaylor commented Jul 16, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@ndonald2

ndonald2 Jul 16, 2015

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

ndonald2 commented Jul 16, 2015

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

@loxy

This comment has been minimized.

Show comment
Hide comment
@loxy

loxy commented Aug 4, 2015

1+

@shumkov

This comment has been minimized.

Show comment
Hide comment
@shumkov

shumkov commented Aug 10, 2015

👍

@loxy

This comment has been minimized.

Show comment
Hide comment
@loxy

loxy Aug 19, 2015

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

loxy commented Aug 19, 2015

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

This comment has been minimized.

Show comment
Hide comment
@benoittgt

benoittgt Aug 19, 2015

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

image

😮

Are they an other existing way to do it ?

benoittgt commented Aug 19, 2015

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

image

😮

Are they an other existing way to do it ?

@danielgtaylor

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor Aug 20, 2015

Owner

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

Owner

danielgtaylor commented Aug 20, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@benoittgt

benoittgt commented Aug 20, 2015

Thanks a lot @danielgtaylor

@mitsuruog

This comment has been minimized.

Show comment
Hide comment
@mitsuruog

mitsuruog commented Sep 18, 2015

👍

@benoittgt

This comment has been minimized.

Show comment
Hide comment
@benoittgt

benoittgt Feb 2, 2016

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.

benoittgt commented Feb 2, 2016

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

This comment has been minimized.

Show comment
Hide comment
@CumpsD

CumpsD Feb 9, 2016

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"
                }
            }

CumpsD commented Feb 9, 2016

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

This comment has been minimized.

Show comment
Hide comment
@benoittgt

benoittgt Mar 10, 2016

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

benoittgt commented Mar 10, 2016

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

@countless-integers

This comment has been minimized.

Show comment
Hide comment
@countless-integers

countless-integers Mar 22, 2016

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

countless-integers commented Mar 22, 2016

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

This comment has been minimized.

Show comment
Hide comment
@bniwredyc

bniwredyc Mar 22, 2016

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:
Attribute table

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'
        }
    }
});

bniwredyc commented Mar 22, 2016

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:
Attribute table

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

This comment has been minimized.

Show comment
Hide comment
@kocou-yTko

kocou-yTko May 2, 2016

any news for this feature?

kocou-yTko commented May 2, 2016

any news for this feature?

@ryanquinlan

This comment has been minimized.

Show comment
Hide comment
@ryanquinlan

ryanquinlan May 6, 2016

Does anyone have this working? I feel like I'm missing something as being able to describe what the request data looks like seems so fundamental to all of this I can't figure out how it's gone overlooked this long. Apiary does an OK job of rendering the attributes sections, but I'm not sure the cloud hosted model is going to work for my production needs.

Tried installing the beta referenced above, but that went all sorts of sideways and I'd expect those changes would have been merged into the master branch at this point anyway.

Appreciate any guidance here. This is what I'm trying to get to render out. I realize that the MSON doesn't support url encoded yet so I'll have to provide the body which is fine. Need the attributes to be displayed though. Hoping to see them look basically like the Parameters section used on the GETs

Thanks!

### Do something awesome [POST]
+ Attributes
    + message (string) - The message
    + author: boba@fett.com (string) - Author of the message

+ Request (application/json)
+ Request (application/x-www-form-urlencoded)
    + Body

            message=foo

+ Response 200
    + Headers

                Location: ID

ryanquinlan commented May 6, 2016

Does anyone have this working? I feel like I'm missing something as being able to describe what the request data looks like seems so fundamental to all of this I can't figure out how it's gone overlooked this long. Apiary does an OK job of rendering the attributes sections, but I'm not sure the cloud hosted model is going to work for my production needs.

Tried installing the beta referenced above, but that went all sorts of sideways and I'd expect those changes would have been merged into the master branch at this point anyway.

Appreciate any guidance here. This is what I'm trying to get to render out. I realize that the MSON doesn't support url encoded yet so I'll have to provide the body which is fine. Need the attributes to be displayed though. Hoping to see them look basically like the Parameters section used on the GETs

Thanks!

### Do something awesome [POST]
+ Attributes
    + message (string) - The message
    + author: boba@fett.com (string) - Author of the message

+ Request (application/json)
+ Request (application/x-www-form-urlencoded)
    + Body

            message=foo

+ Response 200
    + Headers

                Location: ID
@benoittgt

This comment has been minimized.

Show comment
Hide comment
@benoittgt

benoittgt Jun 23, 2016

Seems the related issue has been closed apiaryio/api-blueprint#191. Any news on this one?
Cheers

benoittgt commented Jun 23, 2016

Seems the related issue has been closed apiaryio/api-blueprint#191. Any news on this one?
Cheers

@bloo

This comment has been minimized.

Show comment
Hide comment
@bloo

bloo Jun 24, 2016

This has been an issue for me .. for the entirety of this issue being open. Is aglio being supported these days?

bloo commented Jun 24, 2016

This has been an issue for me .. for the entirety of this issue being open. Is aglio being supported these days?

@SvyatoslavVasiliev

This comment has been minimized.

Show comment
Hide comment
@SvyatoslavVasiliev

SvyatoslavVasiliev Jul 21, 2016

I am really waiting this feature.

SvyatoslavVasiliev commented Jul 21, 2016

I am really waiting this feature.

@philsturgeon

This comment has been minimized.

Show comment
Hide comment
@philsturgeon

philsturgeon Jul 29, 2016

Contributor

Hey @danielgtaylor! Not to pointlessly bump you, but this is a big awesome feature that a lot of folks are looking forward to. Could you give us an update? 😄

Contributor

philsturgeon commented Jul 29, 2016

Hey @danielgtaylor! Not to pointlessly bump you, but this is a big awesome feature that a lot of folks are looking forward to. Could you give us an update? 😄

@danielgtaylor

This comment has been minimized.

Show comment
Hide comment
@danielgtaylor

danielgtaylor Jul 29, 2016

Owner

@philsturgeon and everyone else on this thread, I am very sorry this is not implemented yet. Apiary has kept me extremely busy these last few months and I could not justify spending the time on Aglio. Today is my last day at Apiary. Once I have stable employment again, I hope to work on some new features for Aglio, but right now my focus needs to be elsewhere. I hope you can understand.

P.S. If anybody reading this is hiring either remote or in Seattle, please reach out: danielgtaylor@gmail.com

Owner

danielgtaylor commented Jul 29, 2016

@philsturgeon and everyone else on this thread, I am very sorry this is not implemented yet. Apiary has kept me extremely busy these last few months and I could not justify spending the time on Aglio. Today is my last day at Apiary. Once I have stable employment again, I hope to work on some new features for Aglio, but right now my focus needs to be elsewhere. I hope you can understand.

P.S. If anybody reading this is hiring either remote or in Seattle, please reach out: danielgtaylor@gmail.com

@philsturgeon

This comment has been minimized.

Show comment
Hide comment
@philsturgeon

philsturgeon Aug 1, 2016

Contributor

Hey @danielgtaylor, thanks for getting back to me! Sorry to hear that, I just had a job swap that took a bit longer than I hoped and it can be a f**ker on the money. Pop on the http://slack.apisyouwonthate.com and we'll see if anyone in there is looking, or we can tweet something from the channel. It's got some eyes on it.

In the meantime, maybe you could add https://pledgie.com/ to this repo? I would certainly throw some money at you, and I'm sure some of the other 30ish participants in here would too. Maybe that would help get this feature up and running.

If not, I'll try and get you a PR, but I'm rammed myself. Isn't everyone. 😞

Contributor

philsturgeon commented Aug 1, 2016

Hey @danielgtaylor, thanks for getting back to me! Sorry to hear that, I just had a job swap that took a bit longer than I hoped and it can be a f**ker on the money. Pop on the http://slack.apisyouwonthate.com and we'll see if anyone in there is looking, or we can tweet something from the channel. It's got some eyes on it.

In the meantime, maybe you could add https://pledgie.com/ to this repo? I would certainly throw some money at you, and I'm sure some of the other 30ish participants in here would too. Maybe that would help get this feature up and running.

If not, I'll try and get you a PR, but I'm rammed myself. Isn't everyone. 😞

@zhdanovartur

This comment has been minimized.

Show comment
Hide comment
@zhdanovartur

zhdanovartur commented Aug 31, 2016

+1

@dolfelt

This comment has been minimized.

Show comment
Hide comment
@dolfelt

dolfelt commented Sep 14, 2016

👍

@tucq88

This comment has been minimized.

Show comment
Hide comment
@tucq88

tucq88 Sep 28, 2016

👍 Can't wait for this feature :)

tucq88 commented Sep 28, 2016

👍 Can't wait for this feature :)

@jkryanchou

This comment has been minimized.

Show comment
Hide comment
@jkryanchou

jkryanchou Oct 6, 2016

+1 I'm really looking forward to this feature. What time could the agilo support this.? @danielgtaylor

jkryanchou commented Oct 6, 2016

+1 I'm really looking forward to this feature. What time could the agilo support this.? @danielgtaylor

@angmark0309

This comment has been minimized.

Show comment
Hide comment
@angmark0309

angmark0309 Oct 7, 2016

@bniwredyc, I really like how you present the attributes as a table. Currently, I'm struggling to use your fork. Are there any tutorials to have this custom theme? So far, the steps I took were:

  1. install npm in my local project directory
  2. call npm init, which created the package.json
  3. add the devDependencies in the package.json
  4. run npm install

Results:
created a node_module folder

Please let me know if I am missing any steps. Thank you

angmark0309 commented Oct 7, 2016

@bniwredyc, I really like how you present the attributes as a table. Currently, I'm struggling to use your fork. Are there any tutorials to have this custom theme? So far, the steps I took were:

  1. install npm in my local project directory
  2. call npm init, which created the package.json
  3. add the devDependencies in the package.json
  4. run npm install

Results:
created a node_module folder

Please let me know if I am missing any steps. Thank you

@bniwredyc

This comment has been minimized.

Show comment
Hide comment
@bniwredyc

bniwredyc Oct 7, 2016

@angmark0309 have you configured aglio in your Gruntfile?

bniwredyc commented Oct 7, 2016

@angmark0309 have you configured aglio in your Gruntfile?

@angmark0309

This comment has been minimized.

Show comment
Hide comment
@angmark0309

angmark0309 Oct 7, 2016

@bniwredyc So inside my node_module I only seeaglio-theme-kaitendirectory and inside that, the following files Changelog.md cache node_modules scripts styles README.md lib package.json src templates No Gruntfile. I think I'm installing the fork incorrectly since Im fairly new to this.

angmark0309 commented Oct 7, 2016

@bniwredyc So inside my node_module I only seeaglio-theme-kaitendirectory and inside that, the following files Changelog.md cache node_modules scripts styles README.md lib package.json src templates No Gruntfile. I think I'm installing the fork incorrectly since Im fairly new to this.

@jkryanchou

This comment has been minimized.

Show comment
Hide comment
@jkryanchou

jkryanchou Oct 8, 2016

@bniwredyc Your solution look so nice. and could you send a pull request to the repository in order to help us to use it?

jkryanchou commented Oct 8, 2016

@bniwredyc Your solution look so nice. and could you send a pull request to the repository in order to help us to use it?

@bniwredyc

This comment has been minimized.

Show comment
Hide comment
@bniwredyc

bniwredyc Oct 8, 2016

@angmark0309 I actually don't know how to use themes without grunt-aglio https://www.npmjs.com/package/grunt-aglio

bniwredyc commented Oct 8, 2016

@angmark0309 I actually don't know how to use themes without grunt-aglio https://www.npmjs.com/package/grunt-aglio

@bniwredyc

This comment has been minimized.

Show comment
Hide comment
@bniwredyc

bniwredyc Oct 8, 2016

@ryanchou1991 done. Not that I think it will be merged (there are some other changes), but still.

bniwredyc commented Oct 8, 2016

@ryanchou1991 done. Not that I think it will be merged (there are some other changes), but still.

@jkryanchou

This comment has been minimized.

Show comment
Hide comment
@jkryanchou

jkryanchou Oct 8, 2016

@bniwredyc Awesome job. I would try your solution later. I'm so appreciated for that you could offer that solution. Before I saw your comment. I have used markdown table sheet to instead of the attributes. While it couldn't be compatible with blueprint syntax very well.

jkryanchou commented Oct 8, 2016

@bniwredyc Awesome job. I would try your solution later. I'm so appreciated for that you could offer that solution. Before I saw your comment. I have used markdown table sheet to instead of the attributes. While it couldn't be compatible with blueprint syntax very well.

@marks

This comment has been minimized.

Show comment
Hide comment
@marks

marks Oct 26, 2016

@bniwredyc - you dont have a triple.jade version by any chance, do you?

marks commented Oct 26, 2016

@bniwredyc - you dont have a triple.jade version by any chance, do you?

@antongorodezkiy

This comment has been minimized.

Show comment
Hide comment
@antongorodezkiy

antongorodezkiy Dec 21, 2016

For me I've ended up with attributes in description for now

<?php
    /**
     * Add product
     *
     * **Body Attributes:**
     *
     * | name | type |
     * | --- | --- |
     * | some | some |
     * 
     * @Post("/")
     * @Versions({"v1"})
     * @Transaction({
     *      @Request({
     *          "name": "Some project",
     *          "domain": "some.github.com"
     *      }),
     *      @Response(200, body={}),
     *      @Response(422, body={})
     * })
     */

antongorodezkiy commented Dec 21, 2016

For me I've ended up with attributes in description for now

<?php
    /**
     * Add product
     *
     * **Body Attributes:**
     *
     * | name | type |
     * | --- | --- |
     * | some | some |
     * 
     * @Post("/")
     * @Versions({"v1"})
     * @Transaction({
     *      @Request({
     *          "name": "Some project",
     *          "domain": "some.github.com"
     *      }),
     *      @Response(200, body={}),
     *      @Response(422, body={})
     * })
     */
@OrangeDog

This comment has been minimized.

Show comment
Hide comment
@OrangeDog

OrangeDog Feb 2, 2017

@angmark0309

npm install kaiten-hq/aglio-theme-kaiten -g
aglio --theme-template /usr/local/lib/node_modules/aglio-theme-kaiten/templates/index.jade

OrangeDog commented Feb 2, 2017

@angmark0309

npm install kaiten-hq/aglio-theme-kaiten -g
aglio --theme-template /usr/local/lib/node_modules/aglio-theme-kaiten/templates/index.jade
@jkryanchou

This comment has been minimized.

Show comment
Hide comment
@jkryanchou

jkryanchou commented Feb 2, 2017

👍

@philsturgeon

This comment has been minimized.

Show comment
Hide comment
@philsturgeon

philsturgeon May 11, 2017

Contributor

I made a little progress! One of the folks on slack.apisyouwonthate.com gave me a snippet, which I've expanded to make attributes show in our own custom theme.

In mixins.jade I replaced the JSON Schema output and added this new mixin:

         if request.schema
                - var schema = JSON.parse(request.schema)
                  h5.attributes-title Attributes
                  +AttributeTable(schema)

mixin AttributeTable(schema)

    table.attributes-list(style="width: 100%;")
        thead.attributes-header
            each props, name in schema.properties || []
                tr
                    td
                        strong= self.urldec(name)
                    td.attribute-type
                        != props.type ? (props.enum ? 'enum' : props.type) : 'string'
                    td
                        if schema.required && schema.required.indexOf(name) >= 0
                            span.required-field (required)
                        else
                            span.optional-field (optional)

                    td
                        ul
                            if props.default
                                li.text-info.default
                                    strong Default:&nbsp;
                                    span= props.default

                            if props.example
                                li.text-muted.example
                                    strong Example:&nbsp;
                                    span= props.example

                            if props.enum
                                li.choices
                                    strong Choices:&nbsp;
                                    ul
                                        each value in props.enum
                                            li
                                                code= self.urldec(value)
                                                = ' '

                if props.description
                    tr
                        td
                        td(colspan=3)
                            em
                                != self.markdown(props.description)

                if props.items
                    tr
                        td(colspan=4)
                            div.nested-attributes
                                +AttributeTable(props.items)

                if props.properties
                    tr
                        td(colspan=4)
                            div.nested-attributes
                                +AttributeTable(props)

It works with nested attributes, and with a little CSS on it, it looks... ok well it looks terrible but its good enough to get this task off my desk for now.

screen shot 2017-05-11 at 2 00 37 pm

Obviously im no designer.

Can somebody do something with this? Nicen it up and make a PR to aglio themes?

Contributor

philsturgeon commented May 11, 2017

I made a little progress! One of the folks on slack.apisyouwonthate.com gave me a snippet, which I've expanded to make attributes show in our own custom theme.

In mixins.jade I replaced the JSON Schema output and added this new mixin:

         if request.schema
                - var schema = JSON.parse(request.schema)
                  h5.attributes-title Attributes
                  +AttributeTable(schema)

mixin AttributeTable(schema)

    table.attributes-list(style="width: 100%;")
        thead.attributes-header
            each props, name in schema.properties || []
                tr
                    td
                        strong= self.urldec(name)
                    td.attribute-type
                        != props.type ? (props.enum ? 'enum' : props.type) : 'string'
                    td
                        if schema.required && schema.required.indexOf(name) >= 0
                            span.required-field (required)
                        else
                            span.optional-field (optional)

                    td
                        ul
                            if props.default
                                li.text-info.default
                                    strong Default:&nbsp;
                                    span= props.default

                            if props.example
                                li.text-muted.example
                                    strong Example:&nbsp;
                                    span= props.example

                            if props.enum
                                li.choices
                                    strong Choices:&nbsp;
                                    ul
                                        each value in props.enum
                                            li
                                                code= self.urldec(value)
                                                = ' '

                if props.description
                    tr
                        td
                        td(colspan=3)
                            em
                                != self.markdown(props.description)

                if props.items
                    tr
                        td(colspan=4)
                            div.nested-attributes
                                +AttributeTable(props.items)

                if props.properties
                    tr
                        td(colspan=4)
                            div.nested-attributes
                                +AttributeTable(props)

It works with nested attributes, and with a little CSS on it, it looks... ok well it looks terrible but its good enough to get this task off my desk for now.

screen shot 2017-05-11 at 2 00 37 pm

Obviously im no designer.

Can somebody do something with this? Nicen it up and make a PR to aglio themes?

@11mb

This comment has been minimized.

Show comment
Hide comment
@11mb

11mb Aug 21, 2017

@philsturgeon thx for your code snippet! Im trying it to use for arrays, like in:

###User
+ id: 123 (number)
+ `communication_methods` (array[CommunicationMethods])

The snippet won't work because props.items or props.properties is empty in the AttributeTable mixin.

Your script solves the problem in the template by adding recursiveness, but the data isn't coming from aglio (in case of arrays). Did you solve this?

11mb commented Aug 21, 2017

@philsturgeon thx for your code snippet! Im trying it to use for arrays, like in:

###User
+ id: 123 (number)
+ `communication_methods` (array[CommunicationMethods])

The snippet won't work because props.items or props.properties is empty in the AttributeTable mixin.

Your script solves the problem in the template by adding recursiveness, but the data isn't coming from aglio (in case of arrays). Did you solve this?

@philsturgeon

This comment has been minimized.

Show comment
Hide comment
@philsturgeon

philsturgeon Aug 21, 2017

Contributor
Contributor

philsturgeon commented Aug 21, 2017

@philsturgeon

This comment has been minimized.

Show comment
Hide comment
@philsturgeon

philsturgeon Dec 4, 2017

Contributor

It looks like #337 solves this issue perfectly, but Travis is failing and there's no commit activity. Hopefully somebody picks it up.

Contributor

philsturgeon commented Dec 4, 2017

It looks like #337 solves this issue perfectly, but Travis is failing and there's no commit activity. Hopefully somebody picks it up.

@Grummfy

This comment has been minimized.

Show comment
Hide comment
@Grummfy

Grummfy Jul 19, 2018

it could really be helpful

Grummfy commented Jul 19, 2018

it could really be helpful

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment