{"id":50260056,"url":"https://github.com/alecoletti/apib-to-oas","last_synced_at":"2026-05-27T09:00:57.328Z","repository":{"id":355378344,"uuid":"1227850010","full_name":"alecoletti/apib-to-oas","owner":"alecoletti","description":"Convert API Blueprint into clean OpenAPI 3.xx","archived":false,"fork":false,"pushed_at":"2026-05-13T15:54:24.000Z","size":11891,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-13T17:31:52.924Z","etag":null,"topics":["apiary","apib","apiblueprint","drafter","openai"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alecoletti.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-03T08:53:23.000Z","updated_at":"2026-05-13T15:53:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alecoletti/apib-to-oas","commit_stats":null,"previous_names":["alecoletti/apib-to-oas"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/alecoletti/apib-to-oas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecoletti%2Fapib-to-oas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecoletti%2Fapib-to-oas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecoletti%2Fapib-to-oas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecoletti%2Fapib-to-oas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alecoletti","download_url":"https://codeload.github.com/alecoletti/apib-to-oas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecoletti%2Fapib-to-oas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33558664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["apiary","apib","apiblueprint","drafter","openai"],"created_at":"2026-05-27T09:00:56.395Z","updated_at":"2026-05-27T09:00:57.320Z","avatar_url":"https://github.com/alecoletti.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eApib To OAS\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eConvert API Blueprint (MSON included) into clean OpenAPI 3.0 / 3.1 / 3.2.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"API Blueprint\" src=\"assets/api-blueprint-logo.png\" height=\"64\"\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;➡\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cimg alt=\"OpenAPI\" src=\"assets/openapi-logo.svg\" height=\"64\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/alecoletti/apib-to-oas/actions/workflows/tests.yml\"\u003e\n    \u003cimg alt=\"Tests\" src=\"https://img.shields.io/github/actions/workflow/status/alecoletti/apib-to-oas/tests.yml?branch=main\u0026label=tests\u0026logo=github\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/alecoletti/apib-to-oas/releases\"\u003e\n    \u003cimg alt=\"Release\" src=\"https://img.shields.io/github/v/release/alecoletti/apib-to-oas?include_prereleases\u0026sort=semver\u0026logo=github\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/alecoletti/apib-to-oas/pkgs/container/apib-to-oas\"\u003e\n    \u003cimg alt=\"Container image\" src=\"https://img.shields.io/badge/ghcr.io-apib--to--oas-2496ed?logo=docker\u0026logoColor=white\"\u003e\n  \u003c/a\u003e\n  \u003cimg alt=\"Go version\" src=\"https://img.shields.io/github/go-mod/go-version/alecoletti/apib-to-oas?logo=go\"\u003e\n  \u003ca href=\"LICENSE.txt\"\u003e\n    \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-MIT-red.svg?style=flat\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e [!IMPORTANT]\n\u003e **Apiary shuts down on October 31, 2026.** If you still have `.apib`\n\u003e files hosted there, export them now and run them through\n\u003e `apib-to-oas` before the lights go out for good.\n\n## Why this exists\n\nAPI Blueprint is dead. Oracle is shutting down [Apiary](https://apiary.io)\non October 31, 2026, taking the last hosted `.apib` docs with it.\n[Drafter](https://github.com/apiaryio/drafter), the parser, hasn't\nshipped a release in years. OpenAPI won.\n\nBut a lot of us still have piles of working `.apib` files and no\nappetite for hand-rewriting thousands of lines of MSON into YAML.\nAPIB was — and frankly still is — nicer to write than raw JSON Schema.\nThrowing all that authoring intent away just to chase the new hotness\nfeels like a waste.\n\n`apib-to-oas` is a one-shot migration tool. Point it at your `.apib`,\nget clean OpenAPI back, ship it, and move on. The conversion rules are\nwritten down in [`specs/apib+.md`](specs/apib+.md) (\"Blueprint+\") so\nthe output is predictable, not vibes-based.\n\nIt's a nostalgic project. APIB is dead. Long live API Blueprint.\n\nSure, in the era of AI, writing JSON or YAML by hand isn't really\ncumbersome anymore — an LLM will happily belch out a thousand lines of\nOpenAPI before you finish your coffee. But API Blueprint is still more\nfun to write. The Markdown reads like documentation, MSON looks like\nsomething a human would write, and diffs are actually readable.\n\nMaybe it doesn't need a deeper meaning. It just needs to be useful.\n\n## Quick start\n\n\u003e [!TIP]\n\u003e If you don't want to install anything, the Docker one-liner below is\n\u003e the fastest way to convert a single file. It also doubles as the\n\u003e reference invocation for CI pipelines.\n\n```bash\n# One-shot, via Docker, no install needed:\ndocker run --rm -v \"$PWD\":/work ghcr.io/alecoletti/apib-to-oas:latest \\\n  convert spec.apib -o openapi.yaml\n```\n\nOr install the binary and use it directly:\n\n```bash\napib-to-oas convert spec.apib -o openapi.yaml      # YAML\napib-to-oas convert spec.apib --format json        # JSON to stdout\napib-to-oas lint    spec.apib --strict             # parse + report only\n```\n\n## Install\n\n### Pre-built binary\n\nGrab the tarball for your platform from the\n[releases page](https://github.com/alecoletti/apib-to-oas/releases),\ndrop `apib-to-oas` into your `PATH`, and check it works:\n\n```bash\napib-to-oas version\n```\n\nSHA-256 checksums are published as `checksums.txt` next to the tarballs.\n\n### Docker\n\nA multi-arch image (`linux/amd64`, `linux/arm64`) is pushed to GHCR on\nevery release. Based on `gcr.io/distroless/cc-debian12:nonroot` (~22 MB),\nno shell, no package manager.\n\n```bash\n# Mount your CWD so apib-to-oas can read the .apib file.\ndocker run --rm -v \"$PWD\":/work ghcr.io/alecoletti/apib-to-oas:latest \\\n  convert spec.apib -o openapi.yaml\n\n# Pipe through stdin / stdout, no mount needed.\ncat spec.apib | docker run --rm -i ghcr.io/alecoletti/apib-to-oas:latest \\\n  convert - --format json \u003e openapi.json\n```\n\n### From source\n\n```bash\ntask build\n./bin/apib-to-oas version\n```\n\n…or plain `go build`:\n\n```bash\ngo build -o bin/apib-to-oas ./cmd/apib-to-oas\n```\n\nTasks live in [`Taskfile.yml`](Taskfile.yml). Install\n[Task](https://taskfile.dev) with `brew install go-task`.\n\n## Usage\n\n```text\napib-to-oas convert \u003cfile|-\u003e [flags]\n\nFlags:\n  --oas-version       3.0 | 3.1 | 3.2          (default 3.0)\n  --info-version      override info.version\n  --security-config   path to a security sidecar JSON (specs/apib+.md §9.4)\n  --strict            promote warnings to errors\n  -q, --quiet         suppress non-error diagnostics\n  -f, --format        yaml | json (defaults from -o extension, then yaml)\n  -o, --output        file path or `-` for stdout\n```\n\n`apib-to-oas lint \u003cfile\u003e` parses and reports diagnostics without writing\noutput. Combine with `--strict` for a CI-friendly check.\n\n## How it works\n\n```\n.apib\n  └─ Drafter (vendored, embedded via go:embed)\n       └─ API Elements / Refract JSON\n            └─ Blueprint+ post-processor (this project)\n                 └─ Typed OpenAPI 3.x model\n                      └─ YAML or JSON\n```\n\nDrafter does the heavy parsing. Everything else — schema resolution,\nsecurity, webhooks, hierarchical tags, format inference, the lot — is\npure Go inside `internal/convert`. The pipeline is deterministic: same\ninput, same bytes out, every run.\n\n\u003e [!NOTE]\n\u003e Drafter is the original C++ API Blueprint parser, last released in\n\u003e 2018 and effectively unmaintained. It still works perfectly for\n\u003e well-formed input — `apib-to-oas` ships its own prebuilt binaries\n\u003e (Linux + macOS, amd64 + arm64) baked in via `go:embed` so you never\n\u003e have to install or compile it yourself.\n\n## Layout\n\n| Path                       | What's in it                                     |\n|----------------------------|--------------------------------------------------|\n| `cmd/apib-to-oas/`         | CLI entrypoint                                   |\n| `internal/cli/`            | argument parsing + command dispatch              |\n| `internal/drafter/`        | embedded drafter binary + exec runner            |\n| `internal/drafter/bin/`    | prebuilt drafter binaries (per `GOOS/GOARCH`)    |\n| `internal/convert/`        | Refract → OAS translation                        |\n| `internal/oas/`            | small OAS 3.x model                              |\n| `testdata/`                | sample API Blueprint inputs                      |\n| `specs/apib+.md`           | Blueprint+ language reference                    |\n| `specs/apib+-converter.md` | converter contract (diagnostics, modes, sidecar) |\n\n## Drafter binaries\n\nDrafter source (v5.1.0) is vendored under `third_party/drafter-v5.1.0/`.\nBuild the binary for your host with:\n\n```bash\nscripts/build-drafter.sh\n```\n\nThat writes `internal/drafter/bin/drafter-\u003cGOOS\u003e-\u003cGOARCH\u003e`, which\n`go:embed` bakes into the next `apib-to-oas` build. Without a binary\nfor the current platform, `apib-to-oas convert` returns\n`ErrUnsupportedPlatform`. See `internal/drafter/bin/README.md` for the\nnaming contract.\n\n## Development\n\n```bash\ntask test                  # go test ./...\ntask vet                   # go vet ./...\ntask run -- convert testdata/sample.apib\ntask --list                # show every task\n```\n\nReleasing? See [`docs/RELEASING.md`](docs/RELEASING.md) for the\nrelease-please → goreleaser → GHCR pipeline.\n\n## License\n\n[MIT](LICENSE).\n\n## Acknowledgements\n\n- [API Blueprint](https://apiblueprint.org/) and\n  [Drafter](https://github.com/apiaryio/drafter) by the original Apiary\n  team — none of this works without their decade of effort.\n- The folks who kept writing APIB even after the format was declared\n  dead. This is for you.\n\n## Trademarks\n\nLogos shown for identification purposes only. *API Blueprint* and the\nAPI Blueprint logo are trademarks of Oracle Corporation / Apiary;\nasset taken from the public [`apiaryio/api-blueprint`](https://github.com/apiaryio/api-blueprint/blob/master/assets/logo_apiblueprint.png)\nrepository. *OpenAPI* and the OpenAPI logo are trademarks of the\nOpenAPI Initiative (a Linux Foundation project); asset taken from\nthe [`OAI/OpenAPI-Style-Guide`](https://github.com/OAI/OpenAPI-Style-Guide/tree/main/graphics/vector)\nrepository and used under their published brand guidelines. This\nproject is not affiliated with, sponsored by, or endorsed by either.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falecoletti%2Fapib-to-oas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falecoletti%2Fapib-to-oas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falecoletti%2Fapib-to-oas/lists"}