Basic MSON Support in upcoming release

[catesandrew]

Apiary is currently testing new Blueprint Attributes support using the MSON syntax. Would supporting the new syntax be as simple as updating the existing Jade templates? Are there any other considerations, trade offs?

[danielgtaylor]

@catesandrew thanks for the feature request. I've already been playing around with the MSON support, but haven't gotten around to adding it to the templates. Do you have any ideas of how best to render this data? Do you have a sample of how you'd expect it to look?

As an aside, I'm currently working on a handful of theme enhancements and splitting the rendering code out into theme plugins. You can see the work in progress in the theme-engine and olio-theme branches. You can git clone / checkout the branches in different directories and npm link them to test them out. Included is better offline support, simpler themes (no more loading jQuery and Bootstrap, which were hundreds of KB for example), easier theme color overrides, rendering is much faster (on the order of 0.3 seconds instead of 1.3), all page headers now get links, and I'm working on addressing a few other complaints and feature requests. I'll likely be adding MSON support there unless someone else does it first. I plan to publish these soon with a custom tag until I feel they are ready to become the next major release of Aglio.

[catesandrew]

@danielgtaylor thanks. I will investigate those branches and see if I can come up with something if I get time later this week. I might be able towards end of this week or next. Depends on how fast i get this documentation done for my company's web apis. The MSON is pretty cool nonetheless. Its about time they added that otherwise I was going to jump ship to raml but its not as easy to read as plain markdown, so happy they did it.

[dgmike]

:+1:

[wyattjoh]

Any progress on this issue?

[danielgtaylor]

@wyattjoh the branches I mentioned above are nearing a releasable state. I still need to add support for pagination to the new theme and have to clean up a few things, but they are getting there. I'm also looking into supporting MSON at the moment. The MSON AST is quite complex, and I'm working with the authors of MSON and API Blueprint on ideas of how to make processing it easier for tool authors. I'm hoping to have a plan of attack soon.

[zdne]

:+1:

[catesandrew]

:+1: awesome to hear. i have had no free time, sorry for not being able to assist more

[dgmike]

:+1:

Waiting for this issue…

[vertexod]

:+1: Waiting for this issue too... :(

[danielgtaylor]

For those interested in following along with upstream developments please see apiaryio/fury.js#16. The idea is to have a more stable, unified, and generally easier to use method of traversing and accessing information about an API instead of the current JSON AST produced by the API Blueprint/MSON parser. Once this solidifies a bit, Aglio will be moved to use it and supporting features like MSON will become easier (and is the next task on my list).

Part of the current difficulty in supporting MSON properly is the verbosity and complexity of the MSON AST. The pull request above is going to provide a convenience layer to make everything a bit easier to use and much less likely to break in the future.

[zanerock]

+1 Being able to define a "fully normalized data model" in API Blueprint + aglio would be huge.

I'd be happy to support (== some funding) development on this, if there's a channel for that which would work best.

[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 @catesandrew @dgmike @wyattjoh @vertexod @zanerock

[robbinjanssen]

I'd like to give this a shot, what would be the best way for me to do this? I've already forked your repo and found out that the olio-theme branch contains the theme for the new engine (1. Shouldn't this be a separate repo? 2. It's at version 0.0.5 while the dependency for the aglio beta engine is at 0.0.3, can you update the beta package dependency to 0.0.5 as well instead of 0.0.3?).

Would you prefer something like a mixin that handles the attributes?

Related to https://github.com/danielgtaylor/aglio/issues/103

[zdne]

@robbinjanssen – I leave the @danielgtaylor to answer this but for the record: I have suggested to wait with the MSON in Aglio implementation for MSON refract to be released in Fury.js. With it it will be much more easier to build the support for MSON instead of hacking against the (complex) MSON AST...

[robbinjanssen]

@zdne @danielgtaylor In that case i'll wait for Fury.js, might do some layout stuff already though, see if I can find a proper layout structure to display the attributes.

[danielgtaylor]

With the release of Aglio 2.0 we now support MSON being rendered out as JSON bodies and schemas. I'm going to close this issue, and we can track support for rendering MSON as tables/lists in #103.