Support versioned documentation through git branches/tags
Developers who use a branching/tagging conventions in git (such as GitFlow: http://nvie.com/posts/a-successful-git-branching-model ) would appreciate this being reflected in apiary.
In this way the documentation for the current stable release of an api might be drawn from the repository's master branch, while previous versions would be available at tags, and ongoing work towards the next release could be viewed and discussed at a develop branch.
If the mock api were similarly configurable it'd be extra brilliant.
We are working on the initial workflow support using git branches.
this feature is currently available for Apiary Pro customers only.
If you with to try it out, please do not hesitate to reach out to email@example.com.
Would it be possible to get on the beta? Or is there any update on pushing this out to everyone?
yes, we are testing it with selected customers, and there is a development based on user testing.
Stay tuned! :)
Thomas Koppensteiner commented
+1 for this feature!
Any update on this topic? Is there a beta available?
Jakub Kahovec commented
Would be great to have it !
Any update on when this might take effect? It's going to be show stopper for us if it doesn't come into effect soon ... :-/
Søren Thing commented
+1 - and I like Steve Baker's suggestion.
I really don't understand how you can not have this feature. We are looking to move away from Apiary due to this constraint and the burden it places on us to version control the docs ourselves.
steve baker commented
similar to Evan Owen - we are nice to our API consumers, so retain old APIs
so my take would be closer to allowing multiple apib files to translate to multiple versions?
just a drop down / tabs with the file names (or ideally api name from the file)?
and take an opinioned view on the default document?
- readme.apib < so you could have an intro, and manual links etc
- semver based < so if you have 1.0.0.apib, 1.1.0.apib and 2.0.0.apib you show 2.0.0
- file modified date (though not very automatation friendly..)
unfortunately, there is no update yet. We went through multiple iterations "under the hood", but we have nothing to show yet. Receiving hooks from multiple branches / blueprints is somehow easy, but having an elegant "publishing workflow" is tricky.
I know it's frustrating for you as a user, but please be patient. Once we are going to have some usable beta, we're going to let you know here.
Nathan Gonzalez commented
Arg. Almost 2 years and still nothing. Do we have a status update on this?
Taylor Trimble commented
Glad to see some recent activity on this. Holding our breath!
Evan: Just a thought, I'd say you may want to have them as separate blueprints.
IMHO, once released, your API is "frozen" and development ends. You git cp your blueprint and move on (because, if you are using dredd, you want to test all the older versions, not just the new one).
Good food for thought, thanks.
Evan Owen commented
+1 This is pretty much the only thing preventing us from adopting Apiary wholesale.
Our internal API supports multiple clients including mobile devices, and is constantly evolving. Clients use the Accept header to "lock" themselves to the version they understand, allowing us to add / change data formats and behavior for newer clients, while ensuring older clients continue working indefinitely (so far). In other words, our API is backwards compatible with all previous versions.
Since our API serves up all old versions as well, we really need to maintain documentation for all those older versions. I could see us creating a separate repo for our Apiary docs, with branches and/or tags for each version. Being able to see a diff of a version's blueprint (similar to Github's visual Markdown diffs maybe?) would be helpful as well, but not necessarily required.
Mario Garcia commented
Thorben Stangenberg commented
Phil Ostler commented
Would love this feature.
David Rossellat commented
would love this feature here as well!
simo sentissi commented
This will be very welcomed. this is good!!