snowboard

README

snowboard

API blueprint parser and renderer.

Installation

The latest executables for supported platforms are available from the release page.

Just extract and start using it:

$ wget https://github.com/subosito/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 subosito/packages
$ brew install snowboard

Note: If you want build from master branch you can use brew install --HEAD snowboard

Docker

You can also use automated build docker image on subosito/snowboard:

$ docker pull subosito/snowboard
$ docker run subosito/snowboard -h

Note: Besides image on docker hub, you can also use image on quay.io/subosito/snowboard.

Manual

$ git clone https://github.com/subosito/snowboard.git
$ cd snowboard
$ make install

Note: ensure you have installed Go and configured your GOPATH and PATH.

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 -i API.apib -o output.html

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 -i API.apib -o output.html -t awesome-template.html

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 -i API.apib -o output.html -t awesome-template.html -s

With this flag, You can access HTML documentation on localhost:8088 and any updates on both input and template file will trigger auto-regeneration.

If you need to customize binding address, you can use flag -b.

Use Drafter CLI

If you have drafter command line installed, you can use that for parsing API blueprint within snowboard, just pass -e flag:

$ snowboard -i API.apib -o output.html -e cli

Note: Ensure drafter is already on your PATH directories.

Generate formatted API blueprint

When you have documentation splitted across files, you can customize flags -o and -f to allow snowboard to produce single formatted API blueprint.

$ snowboard -i project/splitted.apib -o API.apib -f apib

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

Help

As usual, you can also see all supported flags by passing -h:

$ snowboard -h
Usage:
  snowboard [OPTIONS]

Options:
  -b string
    	Set HTTP server listen address and port (default "127.0.0.1:8088")
  -e string
    	Use different engine. Supported engines: cgo, cli (default "cgo")
  -f string
    	Format of output file. Supported formats: html, apib (default "html")
  -i string
    	API blueprint file
  -l	Validate input only
  -o string
    	Output file (default "index.html")
  -s	Serve HTML via HTTP server
  -t string
    	Custom template for documentation (default "alpha")
  -v	Display version information

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

Documentation

Overview

Package snowboard API blueprint parser and renderer

Index

• func HTML(tpl string, w io.Writer, b *api.API) error
• func Load(name string, engine Parser) (*api.API, error)
• func Parse(r io.Reader, engine Parser) (*api.API, error)
• func Read(name string) ([]byte, error)
• func Validate(r io.Reader, engine Parser) (*api.API, error)
• type Parser

Functions

func HTML

func HTML(tpl string, w io.Writer, b *api.API) error

HTML renders blueprint.API struct as HTML document

func Load

func Load(name string, engine Parser) (*api.API, error)

Load reads API blueprint from file as blueprint.API struct using selected Parser

func Parse

func Parse(r io.Reader, engine Parser) (*api.API, error)

Parse formats API blueprint as blueprint.API struct using selected Parser

func Read

func Read(name string) ([]byte, error)

Read reads API blueprint from file as bytes

func Validate

func Validate(r io.Reader, engine Parser) (*api.API, error)

Validate validates API blueprint using selected Parser

Types

type Parser

type Parser interface {
	Parse(r io.Reader) ([]byte, error)
	Validate(r io.Reader) ([]byte, error)
	Version() map[string]string
}