I suggest you ...

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.

110 votes
Vote
Sign in
Check!
(thinking…)
Reset
or sign in with
  • facebook
  • google
    Password icon
    I agree to the terms of service
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    Rupert RedingtonRupert Redington shared this idea  ·   ·  Admin →

    24 comments

    Sign in
    Check!
    (thinking…)
    Reset
    or sign in with
    • facebook
    • google
      Password icon
      I agree to the terms of service
      Signed in as (Sign out)
      Submitting...
      • SteelySteely commented  · 

        Would it be possible to get on the beta? Or is there any update on pushing this out to everyone?

      • Thomas KoppensteinerThomas Koppensteiner commented  · 

        +1 for this feature!

        Any update on this topic? Is there a beta available?

      • DavidDavid commented  · 

        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 ThingSøren Thing commented  · 

        +1 - and I like Steve Baker's suggestion.

      • Anonymous commented  · 

        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 bakersteve 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?
        something like:
        - 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..)

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Hi Nathan,

        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.

        Regards,

        Lukas

      • Nathan GonzalezNathan Gonzalez commented  · 

        Arg. Almost 2 years and still nothing. Do we have a status update on this?

      • Taylor TrimbleTaylor Trimble commented  · 

        Glad to see some recent activity on this. Holding our breath!

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        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 OwenEvan 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.

      • Anonymous commented  · 

        Would love this feature.

      • simo sentissisimo sentissi commented  · 

        This will be very welcomed. this is good!!

      ← Previous 1

      Feedback and Knowledge Base