aglio
aglio copied to clipboard
danielgtaylor
Rendering "attributes" section and Data Structures
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.
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.
+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.
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.
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 ;)
+1 Evaluating Blueprint/Apiary and Aglio but being able to document the semantics of the data structure is critical.
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
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?
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.
@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 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 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 [email protected].
@danielgtaylor check your mail :-) Again, if there's anything I can do to contribute. Let me know.
@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.
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 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.
@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 thanks! I've created #130 so let's continue this discussion there.
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 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.
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...
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 ?
@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.
@danielgtaylor It might be worth checking out https://github.com/apiaryio/attributes-kit (Or has this been your plan all along? ;))
@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!
:+1: Thanks @danielgtaylor for your amazing work! Can't wait the next update with attributes rendering improvement as mentioned by @ndonald2 and @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
@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!
+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)
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.
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"
}
}
I see lot's of changes on attributes-kit. Does it mean some change on attributes on Aglio soon ? Thanks a lot
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".
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'
}
}
});
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: [email protected] (string) - Author of the message
+ Request (application/json)
+ Request (application/x-www-form-urlencoded)
+ Body
message=foo
+ Response 200
+ Headers
Location: ID
Seems the related issue has been closed https://github.com/apiaryio/api-blueprint/issues/191. Any news on this one? Cheers
This has been an issue for me .. for the entirety of this issue being open. Is aglio being supported these days?
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? 😄
@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: [email protected]
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. 😞
+1 I'm really looking forward to this feature. What time could the agilo support this.? @danielgtaylor
@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:
- install npm in my local project directory
- call npm init, which created the package.json
- add the devDependencies in the package.json
- run npm install
Results: created a node_module folder
Please let me know if I am missing any steps. Thank you
@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.
@bniwredyc Your solution look so nice. and could you send a pull request to the repository in order to help us to use it?
@angmark0309 I actually don't know how to use themes without grunt-aglio https://www.npmjs.com/package/grunt-aglio
@ryanchou1991 done. Not that I think it will be merged (there are some other changes), but still.
@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.
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={})
* })
*/
@angmark0309
npm install kaiten-hq/aglio-theme-kaiten -g
aglio --theme-template /usr/local/lib/node_modules/aglio-theme-kaiten/templates/index.jade
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:
span= props.default
if props.example
li.text-muted.example
strong Example:
span= props.example
if props.enum
li.choices
strong Choices:
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.
Obviously im no designer.
Can somebody do something with this? Nicen it up and make a PR to aglio themes?
@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?
I did not! Honestly I use Open API and ReDoc these days, it's solved this sort of problem for me.
-- Phil Sturgeon Sent from my iPhone and there's probably typos because I'm probably cycling
On Aug 21, 2017, at 13:40, 11mb [email protected] wrote:
@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?
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.
It looks like https://github.com/danielgtaylor/aglio/pull/337 solves this issue perfectly, but Travis is failing and there's no commit activity. Hopefully somebody picks it up.
