Attribute Support

[ggoodale]

Per the latest spec: https:/apiaryio/api-blueprint/blob/master/examples/10.%20Data%20Structures.md), Attributes provide a means of reusing common structures across multiple API endpoint descriptions. Would be great to get support for these into an upcoming release!

[ndonald2]

+1

[ghost]

Status update on this issue? I'd really like to use MSON to keep my api.md DRY

[yakovkhalinsky]

I appreciate the enthusiasm for this particular feature and I will say that it is being worked on.

However, I am currently maintaining drakov in my spare time, as well with the help of some benevolent contributors.

My estimate (which is by no means a commitment of time) would be at least a month from now.

If anyone using drakov saw their way to contributing this feature in the mean time that would be pretty awesome 👍

[hendrikmaus]

+1

[coryt]

We are just starting to use blueprint to document our api and defined everything in the mson format. Now that we have drakov up and running we realized no data is being returned. So I'd love to help, but not sure what's involved.

[coryt]

so digging further, drakov seems to be handling it properly. The issue is in protagonist not generating the example element properly. I swapped out protagonist for drafter and drakov served up the Attribute parsed json correctly.

[Peleg]

@coryt Yup only after looking in the Dredd source I find that out as well. Using Drafter instead of Protagonist seems to be the solution.

[Peleg]

Drafter.js is deprecated, but in the meantime this seems to help support MSON: #84

[yakovkhalinsky]

OK so the big thing here is that MSON is not being supported by the Apiary parser any more

[yakovkhalinsky]

I would like to understand a bit more why Protagonist is so different, to that effect I've posted a question on the Protagonist repo:
apiaryio/protagonist#83

Please feel free to get involved in the issue in Protagonist, perhaps we can get it done right in protagonist, rather than using a deprecated API Blueprint parser.

If this doesn't go favourably, I would then consider pulling out the Blueprint parsing into a separate node module as a more interim measure.

[pksunkara]

@yakovkhalinsky Drafter.js tool uses Protagonist which uses C++ Drafter.

The purpose of C++ Drafter is to parse the API Blueprint. And Protagonist is the Node.js module wrapping C++ Drafter. Drafter.js is a Node.js module which expands the MSON AST in the API Blueprint AST and renders the sample body and schema.

So, if you want to see the sample body and schema, you have to use drafter.js and not protagonist.

PS: INFORMATION BELOW IS REALLY IMPORTANT

Currently, we are working on expanding the MSON Refract (AST is deprecated) and rendering the sample body and schema inside C++ Drafter itself (apiaryio/drafter#39 & apiaryio/protagonist#84) which when merged provides the sample body and schema in protagonist itself. I would recommend you to use those particular branches or wait until release to start using MSON because MSON AST is deprecated as mentioned in https:/apiaryio/mson-ast

[yakovkhalinsky]

Thanks @pksunkara for that information 👍

[zdne]

@pksunkara is indeed correct with his explanation. Let me add a little bit more of details on the background

Moving from AST to Refract

Due to the growing complexity of the AST (especially MSON AST) and the design flaw that meant breaking changes whenever we will add a top-level node we are moving from AST to Refract tree – https:/refractproject/refract-spec

The API Blueprint AST will be marked deprecated but supported in the months to come including new features. The Blueprint AST data structure nodes will be using Data Structure Refract. That means there will be no access to, now deprecated, MSON AST.

Moving from Drafter.js to (C++) Drafter and its bindings

Drafter.js was a temporary solution – a proof of concept – for producing JSON and JSON Schema out of MSON AST.

We are going to deprecate and discontinue Drafter.js in the favor of (C++) Drafter.

The (C++) Drafter will output API Description Refract and API Blueprint AST (+ Data Structure Refract) on-demand.

The (C++) Drafter will render JSON and JSON Schema from MSON input (internally this represented as the Data Structure Refract).

Protagonist is the (C++) Drafter binding to the Node.js.

Minim an Fury

We provide additional libraries for convenience when working with Refract and / or various description formats.

1. Minim
2. Fury.js

Minim facilitates the operations with a refract tree. Fury.js provides uniform interface through set of "adapters" to various description formats.

Hope this clarifies.

[zdne]

So TL;DR:

You want to use either

• Protagonist + Minim

or

• Fury.js (which comes with Minim)

[zdne]

Note we are looking at releasing the protagonist / Fury.js during this week.

[yakovkhalinsky]

Thanks again to @pksunkara @zdne for the update 👍

I'm leaning towards a refactor of the parsing modules in Drakov 🎱

[yakovkhalinsky]

Will reference this in a new issue for implementing something to replace Drafter.js