{"id":21301725,"url":"https://github.com/funbox/crafter","last_synced_at":"2025-07-11T20:31:21.688Z","repository":{"id":39162991,"uuid":"448043872","full_name":"funbox/crafter","owner":"funbox","description":"API Blueprint parser written in pure JavaScript","archived":false,"fork":false,"pushed_at":"2023-07-19T07:58:55.000Z","size":5763,"stargazers_count":14,"open_issues_count":2,"forks_count":3,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-06-11T16:46:04.798Z","etag":null,"topics":["api-blueprint","apib"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/funbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-14T17:00:54.000Z","updated_at":"2025-03-26T19:57:23.000Z","dependencies_parsed_at":"2024-06-19T00:28:09.781Z","dependency_job_id":"35cbab5c-6ebe-46aa-9185-a6e41c0ba46c","html_url":"https://github.com/funbox/crafter","commit_stats":{"total_commits":1350,"total_committers":26,"mean_commits":51.92307692307692,"dds":0.5918518518518519,"last_synced_commit":"e564ccf27a513b5425478779bbf1d105a18c7d56"},"previous_names":[],"tags_count":232,"template":false,"template_full_name":null,"purl":"pkg:github/funbox/crafter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fcrafter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fcrafter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fcrafter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fcrafter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/funbox","download_url":"https://codeload.github.com/funbox/crafter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fcrafter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264892180,"owners_count":23679249,"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","apib"],"created_at":"2024-11-21T15:50:33.480Z","updated_at":"2025-07-11T20:31:16.676Z","avatar_url":"https://github.com/funbox.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @funboxteam/crafter\n\n[![npm (scoped)](https://img.shields.io/npm/v/@funboxteam/crafter)](https://www.npmjs.com/package/@funboxteam/crafter)\n[![Coverage Status](https://coveralls.io/repos/github/funbox/crafter/badge.svg?branch=master)](https://coveralls.io/github/funbox/crafter?branch=master)\n\n\u003cimg align=\"right\" width=\"160\" height=\"160\"\n     alt=\"Crafter avatar\"\n     src=\"./logo.png\"\u003e\n\n**Crafter** is an [API Blueprint](https://apiblueprint.org/) parser written in pure JavaScript.\nIt is a replacement for Drafter library with some handy features added.\n\n[По-русски](./README.ru.md)\n\n## Rationale\n\nDrafter is written in C++, so the code is pretty complicated and obscure while containing a lot of bugs and legacy.\nIt is hard to understand how some of its parts work. And if bug fixes are welcomed by maintainers, adding a new feature could become an obstacle.\n\nOur company has a tiny percent of C++ projects, so almost none of the developers can maintain Drafter.\n\nThat is why we decided to create own JavaScript replacement which eliminates all previously described limitations,\nis easy to maintain, and allows us to add all needed features.\n\n## Features\n\nCompared to Drafter, this library can offer some important features:\n\n- **Modules**. Now it is possible to split one giant file into parts and inject APIB files into each other, which makes documentation easy to use.\n- **Resource Prototypes** allow you to set up common responses in one place and reuse them through the documentation.\n- Support of **arrays in query strings**.\n- **JSON Schema based types**. In case of complex types it is possible to describe them directly as JSON Schema.\n- **String validation** attributes that describe the expected length of parameters and regular expressions they should match.\n- Describe a **non-HTTP interaction** (as WebSocket) by means of Message section.\n\nAdditional information about how the library works is placed in the [docs](docs) directory.\n\n## Installation\n\nGlobal install:\n\n```bash\nnpm install -g @funboxteam/crafter\n```\n\nLocal install:\n\n```bash\nnpm install --save @funboxteam/crafter\n```\n\n## Usage\n\n### Node.js\n\nParse a file:\n\n```javascript\nconst crafter = require('@funboxteam/crafter');\n\nconst apibFile = 'doc.apib';\nconst ast = (await crafter.parseFile(apibFile))[0].toRefract();\n```\n\nOr provide a string variable containing APIB documentation:\n\n```javascript\nconst crafter = require('@funboxteam/crafter');\n\nconst source = '# My API\\n\\n## List users [GET /users]\\n\\n+ Response 200';\nconst ast = (await crafter.parse(source))[0].toRefract();\n```\n\n### CLI\n\nTo parse a file named `doc.apib` run the next command:\n\n```bash\ncrafter [options] doc.apib\n```\n\n## Options\n\n- `-f, --format \u003cformat\u003e` — set output format of the parse result. Available formats: `json`, `yaml`. Default is `yaml`.\n- `-s, --sourcemap` — export source maps in the parse result.\n- `-d, --debug` — enable debugging mode, which disables catching some of the exceptions.\n- `-l, --langserver` — enable tolerant mode, which is used in language server.\n- `-h, --help` — output usage information.\n\n## Run tests\n\n```bash\nnpm test\n```\n\n## Run in Docker\n\nTo run @funboxteam/crafter as a Docker container execute the next command in the directory with documentation:\n\n```bash\ndocker run \\\n  --rm \\\n  -v $(pwd):/app \\\n  funbox/crafter -f json doc-file.apib\n```\n\nThe default working directory of the image is set to `/app`, therefore it is easier to mount\na host directory into the `/app`. Then just a filename as a parameter will do.\n\n### Docker container in Windows\n\nTo run a container in Windows, add a slash (`/`) before `pwd`.\nThe command will look like this:\n\n```bash\ndocker run \\\n  --rm \\\n  -v /$(pwd):/app/doc \\\n  funbox/crafter -f json doc/doc-file.apib\n```\n\nThere is a chance that the mounted directory is empty. In this case, check that your hard drive is marked as shared.\nThis setting can be found in the settings of Docker Desktop for Windows, Shared Drives section.\nIf the disk is not shared, mark it as `shared`, apply changes, and restart Docker Desktop.\n\n## Why API Blueprint\n\nWe use JSON API widely in the company, so each day our developers face such issues as describing and approving API documentation,\ntracking changes, distributing documentation among partners, and so on. That is why we felt a strong need for convenient tools\nto work with documentation.\n\nHistorically, the battle was between [API Blueprint](https://apiblueprint.org/) and [Swagger](https://swagger.io/).\nWe chose API Blueprint for two reasons. Firstly, the source code of documentation that is described using API Blueprint is more readable to humans.\nSecondly, at the time of research conducted, Swagger lacked several important features, as `One Of` support.\n\n## Credits\n\nAwesome logo for the project was made by [Igor Garybaldi](https://pandabanda.com/).\n\n[![Sponsored by FunBox](https://funbox.ru/badges/sponsored_by_funbox_centered.svg)](https://funbox.ru)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Fcrafter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffunbox%2Fcrafter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Fcrafter/lists"}