{"id":13474683,"url":"https://github.com/bukalapak/snowboard","last_synced_at":"2025-03-26T22:31:08.467Z","repository":{"id":43210360,"uuid":"68568514","full_name":"bukalapak/snowboard","owner":"bukalapak","description":"API blueprint toolkit","archived":true,"fork":false,"pushed_at":"2022-01-15T07:49:46.000Z","size":12900,"stargazers_count":778,"open_issues_count":64,"forks_count":116,"subscribers_count":302,"default_branch":"master","last_synced_at":"2025-03-24T00:38:21.677Z","etag":null,"topics":["api-blueprint","app"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bukalapak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-09-19T04:15:27.000Z","updated_at":"2025-03-21T07:11:09.000Z","dependencies_parsed_at":"2022-09-10T03:03:14.946Z","dependency_job_id":null,"html_url":"https://github.com/bukalapak/snowboard","commit_stats":null,"previous_names":["subosito/snowboard"],"tags_count":210,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bukalapak%2Fsnowboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bukalapak%2Fsnowboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bukalapak%2Fsnowboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bukalapak%2Fsnowboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bukalapak","download_url":"https://codeload.github.com/bukalapak/snowboard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245747576,"owners_count":20665813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-blueprint","app"],"created_at":"2024-07-31T16:01:14.046Z","updated_at":"2025-03-26T22:31:07.306Z","avatar_url":"https://github.com/bukalapak.png","language":"JavaScript","funding_links":[],"categories":["Go","JavaScript","HTML"],"sub_categories":[],"readme":"# snowboard\n\n[![Docker Repository on Quay](https://quay.io/repository/bukalapak/snowboard/status)](https://quay.io/repository/bukalapak/snowboard)\n\nAPI blueprint toolkit.\n\n![Winter theme with playground enabled](packages/snowboard-theme-winter/doc/winter-screenshot.png)\n\n## Packages\n\n| NPM                                                                   | Version                                                                                                                     |\n| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| [snowboard](./packages/snowboard/README.md)                           | [![npm version](https://badge.fury.io/js/snowboard.svg)](https://www.npmjs.com/package/snowboard)                           |\n| [snowboard-reader](./packages/snowboard-reader/README.md)             | [![npm version](https://badge.fury.io/js/snowboard-reader.svg)](https://www.npmjs.com/package/snowboard-reader)             |\n| [snowboard-parser](./packages/snowboard-parser/README.md)             | [![npm version](https://badge.fury.io/js/snowboard-parser.svg)](https://www.npmjs.com/package/snowboard-parser)             |\n| [snowboard-helper](./packages/snowboard-helper/README.md)             | [![npm version](https://badge.fury.io/js/snowboard-helper.svg)](https://www.npmjs.com/package/snowboard-helper)             |\n| [snowboard-linter](./packages/snowboard-linter/README.md)             | [![npm version](https://badge.fury.io/js/snowboard-linter.svg)](https://www.npmjs.com/package/snowboard-linter)             |\n| [snowboard-mock-router](./packages/snowboard-mock-router/README.md)   | [![npm version](https://badge.fury.io/js/snowboard-mock-router.svg)](https://www.npmjs.com/package/snowboard-mock-router)   |\n| [snowboard-seeder](./packages/snowboard-seeder/README.md)             | [![npm version](https://badge.fury.io/js/snowboard-seeder.svg)](https://www.npmjs.com/package/snowboard-seeder)             |\n| [snowboard-packer](./packages/snowboard-packer/README.md)             | [![npm version](https://badge.fury.io/js/snowboard-packer.svg)](https://www.npmjs.com/package/snowboard-packer)             |\n| [snowboard-theme-helper](./packages/snowboard-theme-helper/README.md) | [![npm version](https://badge.fury.io/js/snowboard-theme-helper.svg)](https://www.npmjs.com/package/snowboard-theme-helper) |\n| [snowboard-theme-winter](./packages/snowboard-theme-winter/README.md) | [![npm version](https://badge.fury.io/js/snowboard-theme-winter.svg)](https://www.npmjs.com/package/snowboard-theme-winter) |\n\n### Docker\n\nYou can also use automated build docker image on `quay.io/bukalapak/snowboard`:\n\n```\n$ docker pull quay.io/bukalapak/snowboard\n$ docker run -it --rm quay.io/bukalapak/snowboard help\n```\n\nTo run snowboard with the current directory mounted to `/doc`:\n\n```\n$ docker run -it --rm -v $PWD:/doc quay.io/bukalapak/snowboard html -o outDir API.apib\n```\n\n## Usage\n\nLet's say we have API Blueprint document called `API.apib`, like:\n\n```apib\n# API\n## GET /message\n+ Response 200 (text/plain)\n\n        Hello World!\n```\n\nThere are some scenarios we can perform, like:\n\n```\n# generate HTML documentation\n$ snowboard html -o outDir API.apib\n\n# run mock server\n$ snowboard mock API.apib\n\n# and more, see sections below\n```\n\n## HTML Documentation\n\nTo generate HTML documentation, we can do:\n\n```\n$ snowboard html -o outDir API.apib\n```\n\nAbove command will generate HTML documentation in `output` directory using `snowboard` default template (called `winter`).\n\n### Template Overrides\n\nSnowboard let you override part of the template, you can override template, javascript and stylesheet. You can define it under `html` config:\n\n```js\nconst { resolve } = require(\"path\");\n\nmodule.exports = {\n  html: {\n    overrides: {\n      \"pages/Home.svelte\": resolve(process.cwd(), \"custom/Home.svelte\"),\n      \"lib/helper/colorize.js\": resolve(process.cwd(), \"custom/colors.js\"),\n      \"index.css\": resolve(process.cwd(), \"path-to-style.css\")\n    }\n  }\n};\n```\n\n### HTTP Server\n\nIf you want to access HTML documentation via HTTP, you can use `http` sub-command:\n\n```\n$ snowboard http API.apib\n```\n\nWith this flag, you can access HTML documentation on `localhost:8088`.\n\nIf you need to customize binding address, you can use flag `-b`.\n\n### API Playground\n\nYou can activate the playground feature to let your users interact with your staging or even production API.\n\nPlayground requires a configuration contains supported environments and the name of the default environment. On each environment, you can set an authentication option.\n\nHere's the example of playground configuration along with the different authentication combination supported:\n\n```js\nmodule.exports = {\n  html: {\n    playground: {\n      enabled: true,\n      hidden: false,\n      env: \"development\",\n      environments: {\n        development: {\n          url: \"http://localhost:8087/\",\n          auth: {\n            name: \"apikey\",\n            options: {\n              key: \"api-dev-key\",\n              header: \"X-Api-Key\"\n            }\n          }\n        },\n        staging: {\n          url: \"https://staging.example.com/\",\n          auth: {\n            name: \"basic\",\n            options: {\n              username: \"admin\",\n              password: \"secret\"\n            }\n          }\n        },\n        production: {\n          url: \"https://api.example.com\",\n          auth: {\n            name: \"oauth2\",\n            options: {\n              authorizeUrl: \"https://accounts.example.com/oauth/authorize\",\n              tokenUrl: \"https://accounts.example.com/oauth/access_token\",\n              callbackUrl: \"https://www.example.com\",\n              clientId: \"\u003cclient-id\u003e\",\n              scopes: \"\u003cscope-names\u003e\"\n            }\n          }\n        }\n      }\n    }\n  }\n};\n```\n\nOnce you have a configuration file, named `snowboard.config.js`, you can do:\n\n```\n$ snowboard html -o outDir API.apib\n\n# http sub-command works too\n$ snowboard http API.apib\n```\n\nTo disable playground on particular environment, you can add `playground: false` under environment configuration, like:\n\n```js\nmodule.exports = {\n  html: {\n    playground: {\n      enabled: true,\n      env: \"development\",\n      environments: {\n        development: {\n          url: \"http://localhost:8087/\",\n          playground: false\n        },\n        staging: {\n          url: \"https://staging.example.com/\"\n        }\n      }\n    }\n  }\n};\n```\n\n## Mock Server\n\nAnother snowboard useful feature is having a mock server. You can use `mock` sub-command for that.\n\n```\n$ snowboard mock API.apib\n```\n\nThen you can use `localhost:8087` for accessing mock server. You can customize the address using flag `-b`.\n\nFor multiple responses, you can set `Prefer` header to select a specific response:\n\n```\nPrefer: status=200\n```\n\nYou can also supply multiple inputs for `mock` sub-command:\n\n```\n$ snowboard mock API.apib OTHER.apib\n```\n\n### Mock Server Authentication\n\nThe mock server supports various authentication, you can enable that by passing a configuration file using configuration file `snowboard.config.js`, like:\n\n```\n$ snowboard mock API.apib\n```\n\nHere's the example of the configuration file for mock server:\n\n**API key authentication**\n\n```js\nmodule.exports = {\n  mock: {\n    auth: {\n      name: \"apikey\",\n      options: {\n        key: \"\u003capi-key\u003e\",\n        header: \"\u003cHeader-Name\u003e\"\n      }\n    }\n  }\n};\n```\n\n**Basic authentication**\n\n```js\nmodule.exports = {\n  mock: {\n    auth: {\n      name: \"basic\",\n      options: {\n        username: \"\u003cusername\u003e\",\n        password: \"\u003cpassword\u003e\"\n      }\n    }\n  }\n};\n```\n\n## Other Features\n\nBesides the above features, snowboard also has several useful features for working with API blueprint:\n\n### Validate API blueprint\n\nBesides rendering to HTML, snowboard also support validates API blueprint document. You can use `lint` sub-command.\n\n```\n$ snowboard lint API.apib\n```\n\nUsing flag `--json`, you will receive output as JSON format.\n\n### Render API Element JSON\n\nIn case you need to get API element JSON output for further processing, you can use:\n\n```\n$ snowboard json API.apib\n```\n\n### List Routes\n\nIf you need to list all available routes for current API blueprints, you can do:\n\n```\n$ snowboard list API.apib ANOTHER.apib\n```\n\nUsing flag `--json`, you will receive output as JSON format.\n\n## SSL Support\n\nTo enable HTTPS server, both `http`, and `mock` subcommand supports SSL configuration. You can do:\n\n```\n# http server\n$ snowboard http -S -C cert.pem -K key.pem API.apib\n\n# mock server\n$ snowboard mock -S -C cert.pem -K key.pem API.apib\n```\n\nFor example, for local development, you can utilize [mkcert](https://github.com/FiloSottile/mkcert) to create your local development certificate and use it with snowboard:\n\n```\n# generate localhost certificate\n$ mkcert -install\n$ mkcert localhost\n\n# use the generated certificate with snowboard http or mock subcommand\n$ snowboard http -S -C localhost.pem -K localhost-key.pem API.apib\n\n# you can now access using https://localhost:8088/\n```\n\n## Watcher Support\n\nTo enable auto-regeneration on input files updates, you can add global flag `--watch`\n\n```\n$ snowboard html --watch -o outDir API.apib\n\n# http server\n$ snowboard http --watch API.apib\n```\n\n## Help\n\n```\n$ snowboard help\nAPI blueprint toolkit\n\nVERSION\n  snowboard/4.0.0\n\nUSAGE\n  $ snowboard [COMMAND]\n\nCOMMANDS\n  apib  render API blueprint\n  help  display help for snowboard\n  html  render HTML documentation\n  http  serve HTML documentation\n  json  render API elements json\n  lint  validate API blueprint\n  list  list API routes\n  mock  run mock server\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbukalapak%2Fsnowboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbukalapak%2Fsnowboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbukalapak%2Fsnowboard/lists"}