Autogenerate testable and pretty API docs
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
Login to Github as yourself
Create a team on your organization named
apibotwith 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.
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@example.com so you can verify your account, which is a prerequisite to publishing Github pages.
Create the orphan branch
gh-pageson your repo.
git checkout --orphan gh-pages
- Delete all of the files in the directory (except
- Add an empty file with the name
- Commit, then push to
git push --set-upstream origin gh-pages
Login to Github as the bot
Equip your repo
Login to Github as yourself
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.jsonthen run the following:
npm install firstname.lastname@example.org --save npm install email@example.com --save npm install firstname.lastname@example.org --save npm install email@example.com --save
Modify line 63 of
blueprint-docify/compile_docs.shin 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.
- 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!
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.