{"id":13471028,"url":"https://github.com/apiaryio/drafter","last_synced_at":"2025-03-26T13:30:49.602Z","repository":{"id":27074906,"uuid":"30541396","full_name":"apiaryio/drafter","owner":"apiaryio","description":"API Blueprint Parser (C++)","archived":false,"fork":false,"pushed_at":"2024-03-20T12:38:28.000Z","size":12514,"stargazers_count":302,"open_issues_count":79,"forks_count":54,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-10-30T02:58:04.497Z","etag":null,"topics":["api-blueprint"],"latest_commit_sha":null,"homepage":"https://apiblueprint.org/","language":"C++","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/apiaryio.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":"2015-02-09T15:05:57.000Z","updated_at":"2024-10-28T07:16:47.000Z","dependencies_parsed_at":"2024-10-30T01:51:54.111Z","dependency_job_id":null,"html_url":"https://github.com/apiaryio/drafter","commit_stats":null,"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fdrafter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fdrafter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fdrafter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fdrafter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apiaryio","download_url":"https://codeload.github.com/apiaryio/drafter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245662723,"owners_count":20652070,"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"],"created_at":"2024-07-31T16:00:38.608Z","updated_at":"2025-03-26T13:30:44.586Z","avatar_url":"https://github.com/apiaryio.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"![logo](https://raw.github.com/apiaryio/api-blueprint/master/assets/logo_apiblueprint.png)\n\n# Drafter [![Circle CI](https://circleci.com/gh/apiaryio/drafter/tree/master.svg?style=shield)](https://circleci.com/gh/apiaryio/drafter/tree/master) [![Build status](https://ci.appveyor.com/api/projects/status/7t9qvldmui401dwe/branch/master?svg=true)](https://ci.appveyor.com/project/Apiary/drafter/branch/master)\n\nSnowcrash parser harness\n\n### API Blueprint Parser\nDrafter is complex builder of [API Blueprint](http://apiblueprint.org). Internally it uses [Snowcrash library](https://github.com/apiaryio/snowcrash), reference [API Blueprint](http://apiblueprint.org) parser.\n\nAPI Blueprint is Web API documentation language. You can find API Blueprint documentation on the [API Blueprint site](http://apiblueprint.org).\n\nDrafter also provides the user ability to select the type of the output. There are two possible values:\n\n* **API Elements Parse Result:** Parse Result is defined in API Elements according to [Parse Result Namespace](http://api-elements.readthedocs.io/en/latest/element-definitions/#parse-result-elements).\n* **Normal AST Parse Result:** Parse Result defined by the [API Blueprint AST](https://github.com/apiaryio/api-blueprint-ast) Parse Result. The AST is deprecated and only available in the Drafter command line tool.\n\nBy default, Drafter assumes the Refract Parse Result.\n\nBoth the types of Parse Results are available in two different serialization formats, YAML and JSON. YAML is the default for the CLI.\n\n## Status\n- [Format 1A9](https://github.com/apiaryio/api-blueprint/releases/tag/format-1A9) fully implemented\n\n## Install\nOS X using Homebrew:\n\n```sh\n$ brew install drafter\n```\n\n[AUR package](https://aur.archlinux.org/packages/drafter/) for Arch Linux.\n\nOther systems refer to [installation notes](#installation).\n\n## Usage\n\nDrafter is both a library and a command line tool.\n\n### Command line tool\n\nThe command line tool allows you to parse a blueprint and/or check the validity\nof a blueprint.\n\n```shell\n$ cat \u003c\u003c 'EOF' \u003e blueprint.apib\n# My API\n## GET /message\n+ Response 200 (text/plain)\n\n        Hello World!\nEOF\n\n$ drafter blueprint.apib\nelement: \"parseResult\"\ncontent:\n  -\n    element: \"category\"\n    meta:\n      classes:\n        - \"api\"\n      title: \"My API\"\n...\n```\n\nSee [parse feature](features/parse.feature) for the details on using the `drafter` command line tool.\n\n### C/C++ API\n\n```c\n#include \u003cdrafter/drafter.h\u003e\n```\n\nThe [header](https://github.com/apiaryio/drafter/blob/master/packages/drafter/src/drafter.h) itself is annotated with comments. [C API unit tests](https://github.com/apiaryio/drafter/blob/master/packages/drafter/test/test-CAPI.c) provide more examples.\n\n#### Parse API Blueprint into API Elements\n\nThe `drafter_parse_blueprint_to` function translates a buffered API blueprint into [API\nElements](https://apielements.org/), serialized into one of its supported serialization formats.\n\n```c\ndrafter_error drafter_parse_blueprint_to(\n    const char* source,\n    char** out,\n    const drafter_parse_options* parse_opts,\n    const drafter_serialize_options* serialize_opts);\n);\n```\n\nGiven a pointer to a UTF-8 encoded c-string,\n\n```c\nconst char* blueprint =\n  \"# My API\\n\"\n  \"## GET /message\\n\"\n  \"+ Response 200 (text/plain)\\n\"\n  \"\\n\"\n  \"      Hello World!\\n\";\n```\n\n##### Serialized as YAML\n\nWithout options, the resulting API Elements is serialized as YAML.\n\n```c\nchar* yamlApie = NULL;\nif (DRAFTER_OK == drafter_parse_blueprint_to(blueprint, \u0026yamlApie, NULL, NULL)) {\n    printf(\"%s\\n\", yamlApie);\n}\n\nfree(yamlApie);\n```\n\n##### Serialized as JSON\n\nTweaking `drafter_serialize_options` allows serialization into JSON.\n\n```c\n\ndrafter_serialize_options* serialize_options = drafter_init_serialize_options();\ndrafter_set_format(serialize_options, DRAFTER_SERIALIZE_JSON);\n\nchar* jsonApie = NULL;\nif (DRAFTER_OK == drafter_parse_blueprint_to(blueprint, \u0026jsonApie, NULL, serialize_options)) {\n    printf(\"%s\\n\", jsonApie);\n}\n\nfree(jsonApie);\ndrafter_free_serialize_options(serialize_options);\n```\n\n#### Validate API Blueprint\n\nAPI Blueprint can be validated via `drafter_check_blueprint`.\n\n```c\ndrafter_error drafter_check_blueprint(\n    const char* source,\n    drafter_result** res,\n    const drafter_parse_options* parse_opts);\n```\n\n##### Simple validation\n\nThe return value of `drafter_check_blueprint` indicates validation success.\n\n```c\ndrafter_result* result = NULL;\nif (DRAFTER_OK == drafter_check_blueprint(blueprint, result)) {\n    printf(\"Understood.\\n\");\n}\n\ndrafter_free_result(result);\n```\n\n##### Access warnings and errors\n\nAfter running `drafter_check_blueprint`, the `result` parameter is set to\nreference an API Element containing validation warnings or errors.\n\nBecause the result is an API Element - `drafter_result` - it can be serialized\nas such.\n\n```c\ndrafter_result* result = NULL;\ndrafter_check_blueprint(blueprint, result);\n\nif(result) {\n    char* yamlApie = drafter_serialize(result, NULL);\n    printf(\"%s\\n\", yamlApie);\n    free(yamlApie);\n}\n\ndrafter_free_result(result);\n```\n\nSerialization of API Elements as JSON is achieved by tweaking\n`drafter_serialize_options` as discussed [here](#Serialized-as-JSON).\n\n## Installation\n\nBuilding Drafter will require a modern C++ compiler and\n[CMake](https://cmake.org/install/). The following compilers are tested and\nknown to work:\n\n| Compiler | Minimum Version |\n|----------|-----------------|\n| Clang    | 4.0             |\n| GCC      | 5.3             |\n| MSVC++   | 2015            |\n\nThe following steps can be used to build and install Drafter:\n\n1. Download a stable release of Drafter (release tarballs can be found\n   in [GitHub Releases](https://github.com/apiaryio/drafter/releases)):\n\n    ```sh\n    $ curl -OL \u003curl to drafter release from GitHub releases\u003e\n    $ tar xvf drafter.tar.gz\n    $ cd drafter\n    ```\n\n    Alternatively, you can clone the source repository, for example:\n\n    ```sh\n    $ git clone --recursive https://github.com/apiaryio/drafter.git\n    $ cd drafter\n    ```\n\n2. Build \u0026 Install Drafter:\n\n    POSIX (macOS/Linux):\n\n    ```sh\n    $ mkdir build\n    $ cd build\n    $ cmake ..\n    $ make\n    $ [sudo] make install\n    ```\n\n    NOTE: You can use `cmake -DCMAKE_INSTALL_PREFIX=\"$HOME/.local ..` if you\n    don't want a system wide install.\n\n    Windows:\n\n    ```sh\n    \u003e mkdir build\n    \u003e cd build\n    \u003e cmake ..\n    \u003e cmake --build . --target drafter --config Release\n    ```\n\n    On Windows, `drafter.exe` can be found inside `src\\Release`\n\n3. You can now use Drafter CLI and library:\n\n    ```sh\n    $ drafter --help\n    ```\n\n## Bindings\n\nDrafter bindings in other languages:\n\n- [drafter-npm](https://github.com/apiaryio/drafter-npm) (Node.js)\n- [drafter.js](https://github.com/apiaryio/drafter.js) (Pure JavaScript)\n- [RedSnow](https://github.com/apiaryio/redsnow) (Ruby)\n- [DrafterPy](https://github.com/menecio/drafterpy) (Python)\n\n### CLI Wrapper\n\n- [fury-cli](https://github.com/apiaryio/fury-cli) (Node.js)\n- [Drafter-php](https://github.com/hendrikmaus/drafter-php) (PHP)\n\n## Contribute\n\nFork \u0026 Pull Request\n\nIf you want to create a binding for Drafter please refer to the [Writing a Binding](https://github.com/apiaryio/drafter/wiki/Writing-a-binding) article.\n\n## License\n\nMIT License. See the [LICENSE](https://github.com/apiaryio/drafter/blob/master/LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapiaryio%2Fdrafter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapiaryio%2Fdrafter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapiaryio%2Fdrafter/lists"}