Moving off Apiary: API Blueprint to OpenAPI, with docs and a mock server on the other side
Last checked and updated
Oracle's service-changes page lists the "End-of-Life (EOL) for Apiary Cloud Service effective October 31, 2026", announced on 28 October 2025, and adds: "Customers using API Blueprint format will need to convert to OpenAPI format." Whatever you move to, the work is the same three steps: get the description out, convert it to OpenAPI, and check what the conversion produced. This page runs them on a sample and then shows where the result lives in APIGit. Facts about Apiary and Oracle were read on their own pages on 20 November 2026.
What is known, and what is not
| Stated by Oracle | End of life of Apiary Cloud Service effective 31 October 2026. The notice lists the impacted SKUs "B88650 - Oracle Apiary - Standard" and "B88651 - Oracle Apiary - Professional" and says: "You will no longer be able to use these services after the EOL date, and all remaining instances will be permanently deleted." |
| Seen on 20 November 2026 | Hosted documentation (<name>.docs.apiary.io) answered 502 Bad Gateway. A mock server answered 403 with {"code":"APIARY_EOL","message":"Apiary service access has ended"}. apiary.io, help.apiary.io and the sign-in page loaded, with no notice |
| Not stated anywhere we found | Whether the editor and the CLI still give access to a description, and for how long |
| The format | The API Blueprint specification repository was archived on 8 November 2024; its last commit is from June 2022 |
If your description is only in Apiary, try to get it out today; if it is also in a repository or on a disk, start from that copy.
1. Get the description out
From your own copy first. If the project used GitHub Sync, the file is in your repository on its default branch. A copy fetched earlier, or the one in a colleague's checkout, is as good.
From Apiary, if it still lets you. Apiary's help describes the CLI (we could not test whether it still works after the end-of-life date):
$ gem install apiaryio
$ export APIARY_API_KEY="<token from login.apiary.io/tokens>"
$ apiary fetch --api-name="<API_NAME>" --output="apiary.apib"
A project written in Swagger 2.0 is fetched the same way (--output="swagger.yaml") and needs no conversion. The rendered documentation itself cannot be taken along (Apiary's help: "Currently there is no simple way to print or export a PDF of your rendered documentation"): the description is what you move.
2. Convert API Blueprint to OpenAPI
Neither Oracle nor the API Blueprint site names an official converter. apib2swagger is a maintained open-source one (version 1.17.2, released in November 2026); it writes Swagger 2.0 by default and OpenAPI 3.0.3 with a flag:
$ npx apib2swagger@1.17.2 -i apiary.apib --open-api-3 --yaml -o openapi.yaml
Run on a small polls API (three actions on two resources, with example bodies and no resource group), it produced an openapi: 3.0.3 file with the three operations. What it does with the content:
| In the blueprint | In the OpenAPI file |
|---|---|
| Action names ("List All Questions") | summary, and also operationId, spaces included |
| Example bodies | example on the media type, and a schema inferred from the example |
| Action descriptions | description, empty where the blueprint had none |
+ Parameters | path parameters, with the example as a string |
HOST | servers, with the trailing slash |
Resource groups (# Group ...) | tags; the sample has no group, so its tags are empty |
Schemas inferred from one example are a starting point, not a contract: a field that happened to be absent from the example is absent from the schema, and what is marked required is simply what the example contained.
3. Read what a linter says about the result
The converted file is valid enough to use and has the marks of a conversion. A linter lists them:
$ apigit lint openapi.yaml
openapi.yaml
2:6 warn info-contact Info object must have "contact" object. (info)
7:10 warn oas3-server-trailing-slash Server URL must not have trailing slash. (servers.0.url)
47:20 warn operation-operationId-valid-in-url operationId must not contain characters that are invalid when used in URL. (paths./questions.get.operationId)
48:20 warn operation-description Operation "description" must be present and non-empty string. (paths./questions.get.description)
49:12 warn operation-tags Operation must have non-empty "tags" array. (paths./questions.get.tags)
...
144:20 error oas3-valid-media-example "example" property type must be number (paths./questions/{question_id}.get.parameters.0.example)
11 problems (1 error, 10 warnings, 0 info, 0 hints)
That is a to-do list, in a sensible order:
| Finding | Fix |
|---|---|
oas3-valid-media-example (error) | The parameter example '1' is a string for a number: write 1 |
operation-operationId-valid-in-url | Rename the ids: listQuestions, createQuestion, getQuestion (naming operationIds) |
operation-tags | Add a tag per operation, usually the old resource group (what the rule wants) |
operation-description | Write the missing descriptions |
oas3-server-trailing-slash | Remove the slash |
Then go beyond the list: move repeated schemas to components, check which properties are really required, and add the error responses the blueprint never described. A readiness score gives a rough measure of the distance: the converted sample scored 76 of 100 (apigit score openapi.yaml), losing points for tags, descriptions and undocumented errors.
4. Mock it, and compare with the Apiary mock
A mock generated from the converted file answers with the examples that were in the blueprint:
$ apigit mock serve openapi.yaml --port 4671
Mock of openapi.yaml at http://127.0.0.1:4671 (Ctrl+C to stop). 3 operation(s):
$ curl http://127.0.0.1:4671/questions
[{"question":"Favourite programming language?","published_at":"2015-08-05T08:40:51.620Z","choices":[{"choice":"Swift","votes":2048},{"choice":"Python","votes":1024}]}]
Apiary's help describes its mock as returning the first response defined for an action. This one also checks each request against the description:
$ curl -i -X POST http://127.0.0.1:4671/questions -H 'content-type: application/json' -d '{"question":7}'
HTTP/1.1 422 Unprocessable Entity
{"errors":[{"in":"body","pointer":"/question","message":"must be string"}], ...}
Clients that select a response with Apiary's Prefer: status=404 header send Prefer: code=404 here, once the description declares that status: the converted sample declares only 200 and 201, and a code that is not declared is refused.
5. Where each part of Apiary goes
| In Apiary | In APIGit |
|---|---|
| The description in the Apiary editor, optionally synced to GitHub | A file in a Git repository that APIGit hosts; import the converted file, or migrate the GitHub repository that held the blueprint |
Hosted documentation at <name>.docs.apiary.io | A published documentation site, from any commit or branch; your own domain on the Team and Enterprise plans |
| Mock server | A hosted mock server generated from the description, or scripted |
| API Inspector (captured mock traffic) | The mock server's request log |
| Team roles, private APIs | Organizations, teams and permissions on paid plans; repositories are private by default |
| Dredd tests against the blueprint | Not part of APIGit: keep a contract-testing tool of your choice. Dredd's repository was archived in November 2024 |
Old links to <name>.docs.apiary.io cannot be redirected from your side, since the address belongs to Apiary, and they already fail: publish the new address wherever the old one was linked.
If you used MSON or several files
apib2swagger reads API Blueprint 1A. Check the converted schemas with extra care where the blueprint used MSON data structures or attributes, since those carry type information that examples do not. Apiary's multi-file manifest was already deprecated; convert each file and combine them afterwards (bundling a multi-file description).
Sources
- Oracle Cloud Infrastructure, service changes: End-of-Life for Apiary Cloud Service
- Apiary help, Apiary CLI (apiary fetch)
- Apiary help, GitHub Sync
- Apiary help, mock server
- Apiary help, API Inspector
- Apiary help, exporting documentation
- Apiary help, team settings
- Apiary help, apiary.manifest (deprecated)
- Dredd repository (archived)
- API Blueprint specification repository (archived)
- apib2swagger, API Blueprint to Swagger 2.0 or OpenAPI 3.0
- APIGit documentation, import or migrate files