New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modularity #8

Open
zdne opened this Issue Aug 14, 2013 · 30 comments

Comments

Projects
None yet
@zdne
Copy link
Contributor

zdne commented Aug 14, 2013

Support for multiple API blueprint files within one API.

@rurounijones

This comment has been minimized.

Copy link

rurounijones commented Aug 14, 2013

For those situations where there are a large number of APIs, possibly under control of different groups in a company, this would be an absolute godsend.

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Aug 14, 2013

@rurounijones just for clarification this feature is meant "To be able to split one API description into multiple files".

@zdne zdne referenced this issue Aug 14, 2013

Closed

Data Dictionaries #9

@jrep jrep referenced this issue Dec 18, 2013

Closed

Traits #47

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Jan 31, 2014

Anyone has any thoughts on this? As per my previous comment on Drafter apiaryio/snowcrash#57 (comment)

The options are either add some include / require facility on the top of blueprint or simply fetch all blueprints form a directory and concatenate them together.

Thoughts?

@BRMatt

This comment has been minimized.

Copy link

BRMatt commented Jan 31, 2014

The concatenation is simpler but I feel require would be easier to use as you may want to require, then add something else after.

Will this be just blindly inlining the contents of the file as though it was defined in the patent, or will there be some kind of restriction on the contents of the file(e.g. can they have their own yaml header? Conflicts with parent yaml?) I've got the feeling that no restriction would be better but thought I'd bring it up.

@ecordell

This comment has been minimized.

Copy link
Contributor

ecordell commented Jan 31, 2014

@zdne

First off, I have a rudimentary system for managing this already with Grunt, using simple file concatenation. Our blueprint was becoming unmanageable, and this was a quick and dirty way to split it into files (of note, arbitrarily many files, because they're concatenated by filesystem order). I posted my Gruntfile with a short explanation here.

Given that the concatenation is so simple to roll yourself, it makes sense to me that an "official" tool should be more powerful. I've been thinking more about this, trying to do some research into how this is handled by other systems.

  1. Include/Require
    • Includes would be done at the top of a file, and parts of the file would be referenced within. I think this requires a more robust referencing system than the current [Model Reference][] syntax. Ideally any node in the included file would be addressable - so one might have something like [github.Users.'Create A User'][] or [github][POST /users] or something. (Might also need a prefix like =). Is there a better way to reference a specific node in the AST other than name or url+method?
    • Given that you have a good way to dereference node contents, this could be done with the C Preprocessor which would come with a lot of additional features at no extra cost.
  2. Templating system/Transclusion
    • Non-markdown - The template would be written in a separate templating language, so a template file would not be parseable by snowcrash. An example of something like this is grunt-readme, which looks like it could work out of the box for templating a blueprint file.
    • Markdown - This would be something like the =[]() or :[]() syntax we discussed on the drafter issue. It would still be valid markdown and parseable by snowcrash.
  3. Both
    • Given that you define a syntax for referencing nodes ([github]['Create A User']) and direct transclusion (:[/github.md](/github.md)), it seems like you could easily have both. Perhaps they could have the same general syntax like :[]() and the parser determines if it's a node or a file reference.

Any thoughts on this? Am I missing some options/tools? I'm sort of leaning towards the "both" option with a common syntax for transclusion and node dereferencing, but perhaps that's a little much.

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Feb 4, 2014

Given that the concatenation is so simple to roll yourself, it makes sense to me that an "official" tool should be more powerful

Well eventually maybe yes, but I would like to not over design it and roll out something lean and simple in the begging.

Looking at the problems present problems that needs to be addressed, it is mainly:

  1. Referenced (external) assets - #20 and as discussed in apiaryio/snowcrash#57 (comment)

  2. Splitting blueprint into more manageable logical parts

    For the purpose of splitting I would consider only either a Resource Group or a Resource (e.g. not an action, transaction example, or a request). At least in the beginnings.

Ad 1: I feel referenced assets would be elegantly addressed by the proposal in #20 and discussed apiaryio/snowcrash#57 (comment)

Ad 2: I would not complicate it at all. The only thing I would use for transclusion is the regular markdown syntax e.g. [Some Text](path/to/blueprint/file.apib) or [Some Text](path/to/blueprint/file.apib#resource-name). For inclusion I would follow the same principle as with for assets in drafter e.g. use : prior the reference. Something like https://gist.github.com/zdne/8804418#aliens-question-aliens_question

I think this could suffice for the start?

@ecordell

This comment has been minimized.

Copy link
Contributor

ecordell commented Feb 6, 2014

I think this could suffice for the start?

Agreed. I'm just now realizing that you're making a distinction between including "assets" and including "resources"/"resource groups". I had been thinking of all of them as "nodes" to be included at will.

For the second point, I thought it would be useful to reference the existing MultiMarkdown syntax for transclusion:

This is some text.

{{some_other_file.txt}}

Another paragraph

This seems like a simple way to include resources? (or indeed, arbitrary text/nodes?)

So to clarify my opinion:

  1. I think a good syntax for referenced assets would be :[]() or =[]() as discussed
  2. I think a good syntax for transclusion would be {{ }} as used by multimarkdown.

And also to clarify some vocabulary: I think that when you say "inclusion" you're referring to what I mean when I say "transclusion", that is, entirely replacing a placeholder with text from another file.

If I'm understanding correctly, the difference between "referencing" and "inclusion"/"transclusion" is simply for the sake of rendering, say into html or pdf. To the parser, it doesn't matter if an asset (for example) is referenced or transcluded, the same AST results. Is that correct?

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Feb 10, 2014

  1. I think a good syntax for referenced assets would be : or = as discussed
  2. I think a good syntax for transclusion would be {{ }} as used by multi markdown.

Why to have both instead of just one method? Is there any benefit for syntactically distinguish between those two? Personally I prefer number one since it still renders as a you can follow in a plain Markdown?

I think that when you say "inclusion" you're referring to what I mean when I say "transclusion", that is, entirely replacing a placeholder with text from another file.

Agree, will try to use transclusion from now on. Thanks!

If I'm understanding correctly, the difference between "referencing" and "inclusion"/"transclusion" is simply for the sake of rendering

Not really. In my opinion referring (creating a reference) should really only add a link to the output (AST) and leave the rest on the tooling (#20 (comment))

Translcusion should instruct the parser (or preprocessor) to pull the content in...

@ecordell

This comment has been minimized.

Copy link
Contributor

ecordell commented Feb 25, 2014

Why to have both instead of just one method? Is there any benefit for syntactically distinguish between those two? Personally I prefer number one since it still renders as a you can follow in a plain Markdown?

I could see a case for just having one (and I also prefer the first method, :[][] or =[][]).

The idea behind having two methods for transcluding information was to have two ways to control AST vs. html/md/etc rendering:

  1. A method to link to a document. So :[link][link.md] renders from markdown as a link that looks like :link, but in the AST, that node holds a reference to link.md
  2. A method to transclude a document. So =[link][link.md] renders from markdown as the content of link.md. The AST representation would look the same as 1.

So I could be totally off here, and this may not be necessary, and we should just go with one syntax. But my reasoning was that the way a blueprint is displayed may need to be different from the way it's parsed into an AST.

In my opinion referring (creating a reference) should really only add a link to the output (AST) [...] Translcusion should instruct the parser (or preprocessor) to pull the content in...

I can't tell if you want to treat these as the same thing (one syntax) or as two separate things (two different syntaxes). Both seem fine to me. (Did I just make things more confusing?)

Baggz added a commit that referenced this issue Feb 26, 2014

@zdne zdne added the feature label May 19, 2014

@zdne zdne assigned zdne and unassigned zdne Jul 2, 2014

@vvakame

This comment has been minimized.

Copy link

vvakame commented Dec 3, 2014

👍

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Dec 3, 2014

Just an update here: This is indeed planned and much needed. We are working on the tool that makes this possible. Meanwhile, if you do not rely on Apiary online editor you can you something like https://gist.github.com/danvine/11087404 or another, similar approach (I know at lest of few gulp-based tools for this).

@holic

This comment has been minimized.

Copy link

holic commented Dec 29, 2014

Whiskey now supports the .apib extension and makes editing large Markdown files much easier with its outline view: http://vimeo.com/album/3108294/video/110486733

@bcls

This comment has been minimized.

Copy link

bcls commented Dec 29, 2014

http://9muses.se/erato/ and  http://25.io/mou/ also support .apib if you want a desktop app (for Mac) 

Robert CrooksDirector of Learning Services
Brightcove, Inc

On Dec 29, 2015, at 4:08 PM, Kevin Ingersoll notifications@github.com wrote:

Whiskey now supports the .apib
extension and makes editing large Markdown files much easier with its outline view: http://vimeo.com/album/3108294/video/110486733


Reply to this email directly or view it on GitHub
.

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Jan 4, 2015

Hey @bcls and @holic, thanks for pointing out these editors!

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Apr 27, 2015

Related: #20 (comment)

@foxx

This comment has been minimized.

Copy link

foxx commented May 13, 2015

Has any decision been made by the core developers on this? It's been outstanding since 2013 and no clear cut answer has been given so far, can we get a line drawn on this please?

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented May 13, 2015

Hey @foxx there wasn't any clear decision on this one yet – I am leaning towards the transclusion syntax introduced in Hercule:

FORMAT: 1A

# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).

# Group Gist

:[Gist](blueprint/gist.md)

:[Gists](blueprint/gists.md)

With the exception of

+ Model

    + Body

      ```
      :[](gist.json)
      ```

Because the code blocks should remain opaque to the parser / preprocessor.

Also I do not think the transclusion should work on any level – the files being transcluded should be valid blueprints itself.

As for commitment to this – it is fairly high on the features roadmap – but no ETA just yet.

I would appreciated any comments or thoughts on this and also on features roadmap visibility.

Thanks!

@foxx

This comment has been minimized.

Copy link

foxx commented May 13, 2015

The transclusion syntax seems like the best proposal so far, it's an elegant and clean approach, and better than any other suggestions I've seen so far. Fwiw, +1 from me.

@fesor

This comment has been minimized.

Copy link

fesor commented Jul 10, 2015

any news on this?

approach with transclusion seems good to me, i don't see any disadvantages for it.

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Jul 24, 2015

For the time being I suggest to use Hercule and the :[Gist](blueprint/gist.md) syntax. Will work towards backporting it back into API Blueprint spec and parser toolchain

@adams-sarah

This comment has been minimized.

Copy link
Contributor

adams-sarah commented Nov 6, 2015

Has anything been done for this issue? I'd also like to split up a larger apib file into multiple.
Thanks!

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Nov 9, 2015

Hey @adams-sarah unfortunately not from my side. I do still endorse the use of Hercule (https://github.com/jamesramsay/hercule) as it works pretty well – the only drawback is that you won't be able to edit the multiple files at Apiary.io. Let me know if I can help somehow!

@hendrikmaus

This comment has been minimized.

Copy link

hendrikmaus commented Nov 10, 2015

+1 to the use of hercule https://github.com/jamesramsay/hercule
we have been using it for a while now and hope it will still find its way into the apib specs

@toobulkeh

This comment has been minimized.

Copy link

toobulkeh commented Dec 22, 2015

👍 for the addition of this feature.

I also support a single TOC/index methodology. Transclusion is a bit too flexible and has not scaled in large wiki-based documents in my past experience.

@zdne

This comment has been minimized.

Copy link
Contributor

zdne commented Dec 22, 2015

We will definitely have to bake this into the parser itself to support source map.

In the mean while, we have prepared a real-example to show how to use Hercule – https://github.com/apiaryio/api.apiblueprint.org

@geemus

This comment has been minimized.

Copy link

geemus commented Feb 24, 2016

@zdne in our usage of json-schema (via interagent/prmd) we split it along resource lines and basically enforce a particular directory structure to imply inclusions (more or less it builds a top level schema which has all the stuff in the directory as subschemas, so it changes levels of things). This is obviously pretty specialized to what we were doing and not particularly appropriate in your case, but wanted to share our experience. Compared to that, I think transclusion seems much more elegant/flexible, but it would definitely be nice to also have some straightforward means of having a consolidated TOC/index. Maybe that is similar to what we did though, ie you create an uber blueprint to serve as this index and then transclude/reference the sub-blueprints within it. I can see that happening automagically as being nice, but also as being awkward if it doesn't happen to do just what you want. Anyway, long way of saying I'd be happy to discuss/share my experiences further if that would be helpful.

@DavidBM

This comment has been minimized.

Copy link

DavidBM commented Nov 22, 2017

What is the status of this feature?
We are using the Pro plan in Apiary.io and we need this feature

@kylewelsby

This comment has been minimized.

Copy link

kylewelsby commented Nov 22, 2017

@DavidBM I had the same problem. how I got around this is to have two apiary.apib documents.

Uncompiled

apiary-source.apib - a uncompiled source that makes use of the Include Feature

FORMAT: 1A
HOST: https://api.example.com

# Hello World

<!-- include(blueprint/posts.apib) -->

Compile

You can simply run:

aglio --input apiary-source.apib --compile --output apiary.apib

Your apiary.apib should now include the contents of blueprint/posts.apib within.

@DavidBM

This comment has been minimized.

Copy link

DavidBM commented Nov 24, 2017

Hi, thanks! Yeah, but then you can't edit the documents in apiary.io

We already had the customized solution with Hercule, but the point of paying apiary pro for us is to let the product managers to update the documentation without entering in git. I'm afraid that this is a completely blocker for us and we will cancel the contract with Apiary if this is not solved.

I wouldn't expect this to be in this state after having Hercule and other tools for so many time available.

This is very very disappointing :(

@clucasalcantara

This comment has been minimized.

Copy link

clucasalcantara commented Aug 5, 2018

Hello everyone, I'm sorry for getting here late and reopening and digging old stuff. If this isn't the right place please forgive me. But, doing a research to develop blueprint mocks I've found this discussion and this is the closest that I've could find until now.

I'm struggling to split my responses by model :(. Isn't it possible to referer a model into a different folder?
I would like to have inside my blueprints folder all my requests, and, for example into a separated models folder all my entities models (MSON/MD/JSON/whatever files, that whose fit) to reuse them into different responses easily. Anyone have success doing this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment