Search code examples
apiblueprintaglio

Data abstraction in API Blueprint + Aglio?

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.

Solution

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