2

Reading the API Blueprint specification, it seems set up to allow one to specify 'Data Structures' like:

  • Address
    • street: 100 Main Str. (string) - street address
    • zip: 77777-7777 (string) - zip / postal code

...

  • Customer:
    • handle: mrchirpy (string)
    • address: (address)

And then in the model, make a reference to the data structure:

  • Model

    [Customer][]

It seems all set up that by referencing the data structure it should generate documentation and examples in-line with the end points.

However, I can't seem to get it to work, nor can I find examples using "fully normalized data abstraction". I want to define my data structures once, and then reference everywhere. It seems like it might be a problem with the tooling, specifically I'm using aglio as the rendering agent.

It seems like all this would be top of the fold type stuff so I'm confused and wondering if I'm missing something or making the wrong assumptions about what's possible here.

zanerock
  • 3,042
  • 3
  • 26
  • 35

1 Answers1

0

@zanerock, I'm the author of Aglio. The data structure support that you mention is a part of MSON, which was recently added as a feature to API Blueprint to describe data structures / schemas. Aglio has not yet been updated to support this, but I do plan on adding the feature.

Daniel
  • 8,212
  • 2
  • 43
  • 36
  • 1
    That's more or less what I thought. Thanks. I'll keep an eye on the development. – zanerock Apr 21 '15 at 20:47
  • Is it now implemented? or is there any way to reference datastructure easily? – EsseTi Feb 03 '16 at 12:40
  • @EsseTi yes, to some degree. You can now use MSON and Aglio will render out examples and JSON Schema based on it, and you can use inheritance and mixins. MSON can be used anywhere that `+ Attributes` can be used, plus you can use a `# Data Structures` section to define structures you will reference in resources/actions. – Daniel Feb 04 '16 at 22:01