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
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.
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.
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.
请发表评论