Skip to content

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 OracleEnd 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 2026Hosted 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 foundWhether the editor and the CLI still give access to a description, and for how long
The formatThe 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 blueprintIn the OpenAPI file
Action names ("List All Questions")summary, and also operationId, spaces included
Example bodiesexample on the media type, and a schema inferred from the example
Action descriptionsdescription, empty where the blueprint had none
+ Parameterspath parameters, with the example as a string
HOSTservers, 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:

FindingFix
oas3-valid-media-example (error)The parameter example '1' is a string for a number: write 1
operation-operationId-valid-in-urlRename the ids: listQuestions, createQuestion, getQuestion (naming operationIds)
operation-tagsAdd a tag per operation, usually the old resource group (what the rule wants)
operation-descriptionWrite the missing descriptions
oas3-server-trailing-slashRemove 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 ApiaryIn APIGit
The description in the Apiary editor, optionally synced to GitHubA 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.ioA published documentation site, from any commit or branch; your own domain on the Team and Enterprise plans
Mock serverA hosted mock server generated from the description, or scripted
API Inspector (captured mock traffic)The mock server's request log
Team roles, private APIsOrganizations, teams and permissions on paid plans; repositories are private by default
Dredd tests against the blueprintNot 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

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish