Blueprint docify

Autogenerate testable and pretty API docs

TL;DR

Add your API spec as api.apib in the root of your repo and push!

It will make great API docs for each branch that has an API blueprint (.apib). Your documents will be available at http://org.github.io/repo/branch. See the branches on this repo and thier related docs:

These are for visual purposes only, do not read as spec

• http://kirkstrobeck.github.io/blueprint-docify/gist-fox-api/
• http://kirkstrobeck.github.io/blueprint-docify/real-world-api/
• http://kirkstrobeck.github.io/blueprint-docify/simplest-api/

Getting started

1. Login to Github as yourself

2. Create a team on your organization named apibot with admin access to the repos you want to docify. This team will help to limit access by being intentional about what repos are added. ie. renewableapibot for this repo.

3. Create a new Github account for your api bot (ie. renewableapibot). If you're using Google email, append the first part of your email with +bot, like [email protected] so you can verify your account, which is a prerequisite to publishing Github pages.

4. Create the orphan branch gh-pages on your repo.

• Use git checkout --orphan gh-pages
• Delete all of the files in the directory (except .git obviously)
• Add an empty file with the name .gitignore. (run touch .gitignore)
• Commit, then push to gh-pages with git push --set-upstream origin gh-pages

5. Login to Github as the bot

6. Create a new Shippable account as the bot (login with Github). Add your repo on the settings page.

7. Copy the Shippable deployment key and add it as an SSH key in Github (not under the repo, under the bot’s account).

Equip your repo

1. Login to Github as yourself

2. Pull down this repo and copy the following files to the repo you want to equip:

   blueprint-docify
   package.json
   shippable.yml

   If you already have a package.json then run the following:

   npm install [email protected] --save
   npm install [email protected] --save
   npm install [email protected] --save
   npm install [email protected] --save

3. Modify line 63 of blueprint-docify/compile_docs.sh in the repo you want to equip.

Now, because of shippable.yml, you should be ready to rock. Shippable should build out your API documentation on push. If you don’t want to run Shippable on a specific push, include [skip ci] in your commit message.

Why it was made

API blueprint is a great new flavor of Markdown for clear API spec. We were using Apiary for a bit, it’s a great place to get started with apib, but it fell short as a production-ready tool for any stack.

Problems with Apiary or any other tool like it:

• No way to signify if the response or endpoint is a hopeful mock, old and should be deleted, in production, in beta, wont do, etc.
• Can’t test against API spec with custom conditional notes, etc. What stage is each endpoint, etc.
• Maintain n number of apiary’s per-branch * per-repo * per-org where n is way too many (more than 1). Where is the documentation with these links? How do you handle elegant naming conventions when it is a shared namespace, ie. http://docs.notelegant.apiary.io/
• It’s is slow, sometimes down, etc. (it’s another external dependency)
• Is Github our source of truth? or where do I look? Is that up to date? Where’s the changelog!
• Please show me the diff between this API and that one (different branches)
• Apiary only lets me write one file per repo! I have other branches, each with a unique API spec, because the API is in development!

FAQ

Q: Can a private repo write a public Github page? Private repos will write public pages :D

Q: So how does this publish multiple branches docs at once? multiple github pages? It actually pulls gh-pages from your repo to the CI and overwrites the folder with the name of the branch you are pushing to the CI from

Q: So one rendered branch at a time? Yah, when you update an api spec and push, it writes the docs for that branch

Q: What if there’s already an api bot on my repo? If you already have an api bot in your Github organization (someone else followed these steps already), then simply give it access to the required repo(s) and try to add it to the same CI account (doesn’t make sense to spread out CI implementations).

Q: What is this API I see in the examples? We used the example API blueprint from API Blueprint Examples

Q: how many emails you'll get? I believe its just for the Github account confirmation. if the email is in the bot’s public profile on Github, Shippable will grab it and use that email for pass/fail messages.

Roadmap

• Dredd integration
• API mock
• A Postman integration, either apiary2postman or Blueman

Thank you!

• API blueprint contributors!
• Aglio - An API Blueprint renderer with theme support that outputs static HTML
• Graphic hacked from google image search