snowboard
API blueprint toolkit.
Installation
The latest executables for supported platforms are available from the release page.
Just extract and start using it:
$ wget https://github.com/bukalapak/snowboard/releases/download/${version}/snowboard-${version}.${os}-${arch}.tar.gz
$ tar -zxvf snowboard-${version}.${os}-${arch}.tar.gz
$ ./snowboard -h
Alternatively, you can also use options below:
Homebrew
$ brew tap bukalapak/packages
$ brew install snowboard
Note: If you want build from master branch you can use
brew install --HEAD snowboard
Arch Linux
Snowboard available as AUR package.
$ pacaur -S snowboard
Docker
You can also use automated build docker image on quay.io/bukalapak/snowboard
:
$ docker pull quay.io/bukalapak/snowboard
$ docker run -it --rm quay.io/bukalapak/snowboard help
To run snowboard with the current directory mounted to /doc
:
$ docker run -it --rm -v $PWD:/doc quay.io/bukalapak/snowboard html -o output.html API.apib
Manual
$ git clone https://github.com/bukalapak/snowboard.git
$ cd snowboard
$ make install
Note: ensure you have installed Go and configured your
GOPATH
andPATH
.
Usage
Let's say we have API Blueprint document called API.apib
, like:
# API
## GET /message
+ Response 200 (text/plain)
Hello World!
There are some scenarios we can perform:
Generate HTML Documentation
To generate HTML documentation we can do:
$ snowboard html -o output.html API.apib
Above command will generate ouput.html
using snowboard
default template (called alpha
).
Using Custom Template
If you want to use custom template, you can use flag -t
for that:
$ snowboard html -o output.html -t awesome-template.html API.apib
To see how the template looks like, you can see snowboard
default template located in templates/alpha.html.
Serve HTML Documentation
If you want to access HTML documentation via HTTP, especially on local development, you can pass -s
flag:
$ snowboard html -o output.html -t awesome-template.html -s API.apib
With this flag, You can access HTML documentation on localhost:8088
.
If you need to customize binding address, you can use flag -b
.
Auto-regeneration
To enable auto-regeneration on both input and template file updates, you can add global flag --watch
$ snowboard --watch html -o output.html -t awesome-template.html -s API.apib
Optionally, you can also use --watch-interval
to enable polling interval.
$ snowboard --watch --watch-interval 100ms html -o output.html -t awesome-template.html -s API.apib
Serve HTML from Docker container
If you want to serve HTML documentation from Docker container, don't forget to bind address and port in the contaier plus bind ports of host and container by -p
option of Docker command.
$ docker run -it --rm -v $(pwd):/doc -p 8088:8088 bukalapak/snowboard html -o output.html -b 0.0.0.0:8088 -s API.apib
Generate formatted API blueprint
When you have documentation splitted across files, you can customize flags -o
to allow snowboard
to produce single formatted API blueprint.
$ snowboard apib -o API.apib project/splitted.apib
Validate API blueprint
Besides render to HTML, snowboard also support validates API blueprint document. You can use lint
subcommand.
$ snowboard lint API.apib
Mock server from API blueprint
Another snowboard useful feature is having mock server. You can use mock
subcommand for that.
$ snowboard mock API.apib
Then you can use localhost:8087
for accessing mock server. You can customize the address by passing flag -b
.
For multiple responses, you can set X-Status-Code
or Prefer
header to select specific response:
X-Status-Code: 200
// or
Prefer: status=200
External Files
You can split your API blueprint document to several files and use partial
helper to includes it to your main document.
{{partial "some-resource.apib"}}
Alternatively, you can also use HTML comment syntax to include those files:
<!-- partial(some-resource.apib) -->
or
<!-- include(some-resource.apib) -->
Seed Files
As your API blueprint document become large, you might move some value to separate file for easier organization and modification. Snowboard supports this as well.
Just place your values into a json file, say, seed.json
:
{
"official": {
"username": "olaf"
}
}
Then on your API blueprint document you can use seed
comment helper:
# API
<!-- seed(seed.json) -->
Our friendly username is {{.official.username}}.
Multiple seeds are also supported.
API Element JSON
In case you need to get API element JSON output for further processing, you can use:
$ snowboard json API.apib
Help
As usual, you can also see all supported flags by passing -h
:
$ snowboard help
NAME:
snowboard - API blueprint toolkit
USAGE:
snowboard [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
COMMANDS:
lint Validate API blueprint
html Render HTML documentation
apib Render API blueprint
json Render API element json
mock Run Mock server
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--help, -h show help
--version, -v print the version
FAQ
-
I am using Vim and snowboard file watcher doesn't trigger auto-regeneration, any idea?
It is known issue due Vim backup scheme. You can set on your
.vimrc
:set nobackup set nowritebackup
Examples
You can see examples of snowboard
default template outputs, in examples/alpha directory. They looks like:
- Named Resource and Actions
- Real World API
- And many more...
All of the examples are generated from official API Blueprint examples