Apiary is shutting down. Oracle has posted an announcement of the termination of Apiary support, and API tooling vendors report that the hosted service is expected to shut down around September 2026. Oracle acquired Apiary in January 2017, deprecated paid plans in 2018, and allowed related open-source tools such as Dredd and Gavel to become archived. If your API documentation is hosted on apiary.io, this is no longer an alternatives evaluation: you need an export and migration plan.
Apidog is a practical Apiary replacement because it covers the same design-first workflow—spec editing, hosted interactive docs, and mock servers—while adding automated API testing, spec-driven response validation, and CI integration. It is free for up to four users, with paid plans starting at $9 per user per month.
The migration caveat is important: Apidog does not directly import API Blueprint. For Blueprint projects, convert the specification to OpenAPI once, validate the result, and then import it. This guide covers that process and explains when another destination may be a better fit.
What is happening to Apiary?
Apiary, founded in 2011, helped establish the design-first API workflow. It introduced API Blueprint, a Markdown-based API description format created before OpenAPI became the dominant standard. It also provided hosted documentation, mock servers, GitHub sync, and contract-testing tools including Dredd and Gavel.
After Oracle acquired Apiary in January 2017:
- Paid tiers were deprecated in 2018.
- New product development effectively stopped.
- Dredd and Gavel were archived.
- Oracle announced the termination of Apiary support.
- The hosted service is expected to end around September 2026.
As Bump.sh explains in its Apiary farewell post, export API descriptions before the shutdown. Once the hosted service is gone, there is nothing left to export.
This creates two immediate tasks:
- Export everything stored only in Apiary. That includes API descriptions, documentation prose, examples, and team configuration.
- Move API Blueprint projects to OpenAPI. API Blueprint no longer has a maintained platform ecosystem, while OpenAPI is supported across modern API tooling.
What your replacement needs to cover
Before choosing a destination, list the Apiary capabilities your team currently uses:
- Design-first spec editing: Write API Blueprint or OpenAPI and update documentation from the spec.
-
Hosted interactive documentation: Publish reference docs on an
apiary.ioURL. - Mock servers: Provide consumers with an endpoint before the real backend is ready.
- GitHub sync: Keep the API description in a repository and synchronize changes.
- Contract testing via Dredd: Run spec-defined requests against a real implementation and detect drift.
For Dredd specifically, see how to validate your API against its spec without Dredd.
A migration target should cover the complete workflow: design, documentation, mocking, and validation—not only documentation rendering.
Why Apidog is a strong Apiary replacement
Apidog is an API development platform used by over 500,000 developers. It supports API design, documentation, mocking, debugging, and automated testing from a shared API definition.
For an Apiary migration, the relevant capabilities are:
Design-first OpenAPI editing
Use visual and code editors for OpenAPI 3.x. Define endpoints, schemas, examples, and authentication once, then use that definition to generate docs, mocks, and tests.Hosted interactive documentation
Publish API reference documentation with a try-it console, versioning, and custom domains. This avoids depending on anapiary.ioURL that disappears with the service.Schema-aware mock servers
Apiary mocks replay written examples. Apidog can generate mock responses from schemas and supports custom mock rules when you need deterministic output.Contract validation and automated tests
Create test scenarios that send requests to your implementation, validate responses against OpenAPI schemas, and run assertions. You can run tests in CI with the Apidog CLI.MCP-based API documentation access
Apidog documentation can also be published alongside an MCP server so AI agents can read API specifications directly. See what is Apidog MCP Server.
Migrate from Apiary step by step
Apidog imports Swagger 2.0, OpenAPI 3.0, OpenAPI 3.1, Postman collections, HAR, RAML, JMeter, apiDoc, I/O Docs, WADL, and Google Discovery formats. See the Apidog import documentation.
API Blueprint is not a supported direct import format, so Blueprint projects need an OpenAPI conversion step first.
1. Export every Apiary project now
For every Apiary project:
- Open the project in the Apiary editor.
- Download the API description.
- Export or copy documentation prose and examples that may not be embedded in the spec.
- If the project uses GitHub sync, verify the repository contains the latest version.
- Save exported files in a migration branch or archive repository.
If a project was authored in OpenAPI 3.0, you can skip conversion and continue directly to import.
Do this before evaluating platforms. Export is the deadline-sensitive part of the migration.
2. Convert API Blueprint to OpenAPI
For API Blueprint projects, convert the exported .apib file to OpenAPI.
Useful tools include:
-
api-spec-converterby LucyBot, which supports API Blueprint conversion -
apib2swagger, a Blueprint-to-Swagger/OpenAPI converter -
openapi-format, which can normalize converted output and help upgrade it to OpenAPI 3.1
A typical workflow looks like this:
# Convert an API Blueprint file to an OpenAPI document.
api-spec-converter api.apib --from api_blueprint --to openapi_3 --syntax yaml > openapi.yaml
Then validate the generated file with your preferred OpenAPI linter:
vacuum lint openapi.yaml
Review these areas manually after conversion:
- Authentication: API Blueprint did not formally model auth schemes, so converters may not recover API keys, bearer tokens, OAuth flows, or security requirements accurately.
- Markdown prose: Check content in Blueprint sections that was not attached to endpoint descriptions.
- Request and response examples: Confirm examples remain valid and match expected schemas.
- Status codes and headers: Validate that generated responses preserve the intended behavior.
For most APIs, this is an hour of review rather than a week of rewriting.
3. Import the OpenAPI file into Apidog
In Apidog:
- Create or open a project.
- Go to Project Settings.
- Choose Manual Import.
- Upload the OpenAPI file, or import from a URL.
- Review imported endpoints, schemas, examples, and authentication settings.
After import, you can immediately:
- Browse generated reference documentation.
- Publish interactive docs.
- Use generated mock endpoints.
- Create test scenarios for endpoint validation.
4. Rebuild integrations that depended on Apiary
After the spec is imported:
Set a custom domain for documentation
Do not leave your public docs tied to a tool-owned URL if you can avoid it.Replace Apiary mock URLs
Send consumers the new mock base URL and document any behavior changes, especially if they relied on hand-written Apiary examples.-
Replace Dredd checks with test scenarios
Create tests that:- Send real requests to your deployed API.
- Validate response status codes and schemas.
- Assert business-specific values.
- Run with data-driven inputs where needed.
- Execute locally and in CI through the CLI.
Add the OpenAPI file to source control
Make the specification part of your normal pull-request workflow.
A single API can usually move in an afternoon. A portfolio of Blueprint APIs may take a sprint, primarily because authentication and documentation prose need manual verification.
Apiary vs. Apidog
| Apiary (today) | Apidog | |
|---|---|---|
| Future | Shutting down; support terminated, service end expected around September 2026 | Actively developed |
| Spec format | API Blueprint, later OpenAPI 3.0 | OpenAPI 3.x, with Swagger 2.0 import; visual and code editors |
| Hosted docs | Yes, on apiary.io URLs | Yes, with custom domains, versioning, and a try-it console |
| Mock server | Replays written examples | Schema-aware smart mocks and custom rules |
| Contract testing | Dredd, now archived | Test scenarios, schema validation, and CLI-based CI runs |
| Automated test suites | No | Yes, including visual scenarios and data-driven cases |
| GitHub sync | Yes | Spec import/sync from URL or file; branch-based versioning |
| Price | Free; paid plans were deprecated in 2018 | Free for up to 4 users, then $9 per user/month |
| Export path | API Blueprint or OpenAPI download | OpenAPI, Markdown, and HTML exports |
What replacing a free tool costs
Apiary's remaining advantage was its price. Using listed prices, the annual cost comparison looks like this:
| Team size | Apidog per year | SwaggerHub Team per year | ReadMe Pro per year |
|---|---|---|---|
| 3 people | $0 (free plan) | $1,240 | $3,000 |
| 5 people | $540 | $2,066 | $3,000 |
| 10 people | $1,080 | $4,133 | $3,000 |
| 25 people | $2,700 | $10,332 | $3,000 |
If you only need to render one specification, docs-only tools may also have free tiers. The comparison matters when you need the workflow that made Apiary useful: documentation, mock servers, testing, and collaboration.
For a team of up to four users, Apidog's free plan covers the migration workflow. In that case, the primary migration cost is the conversion and validation time.
When Apidog is not the right fit
Apiary is going away, but Apidog is not the only possible destination.
You only need documentation rendering
If your API specs are produced and tested elsewhere, a docs-first platform such as Bump.sh can be a reasonable choice. You still need to convert API Blueprint to OpenAPI first.You are standardizing on SmartBear tooling
SwaggerHub is close to Apiary's hosted-spec-registry model. Review its per-seat cost and metered test execution model. For a comparison, see the best SwaggerHub alternative.Your priority is API design governance
Stoplight provides style-guide and governance tooling for larger platform teams. Review the best Stoplight alternative before committing.You want to continue using API Blueprint
Avoid making that the long-term plan. The format's ecosystem is unmaintained, and OpenAPI is the broadly supported replacement. Convert once and continue with a maintained standard. The API Blueprint guide is useful historical context.
Frequently asked questions
When does Apiary shut down?
Oracle has announced the termination of Apiary support. API tooling vendors report that the hosted service is expected to shut down around September 2026.
Treat the date as a reason to export immediately: the product is already unmaintained, and waiting increases the risk of losing access to hosted project data.
Can Apidog import API Blueprint directly?
No. Apidog imports OpenAPI/Swagger, Postman, HAR, RAML, JMeter, apiDoc, I/O Docs, WADL, and Google Discovery formats.
Convert API Blueprint to OpenAPI first using a tool such as api-spec-converter or apib2swagger, then import the resulting OpenAPI file. Manually review authentication after conversion.
What replaces the Apiary mock server?
Apidog's smart mock server replaces it. Apiary replayed examples you wrote; Apidog can generate responses from API schemas and lets you configure custom mock rules for specific cases.
Imported endpoints receive mock capabilities without needing to manually create every response example.
What replaces Dredd for contract testing?
Use Apidog automated test scenarios. They can send requests to your implementation, validate responses against your API specification, run assertions, execute data-driven cases, and run in CI through the Apidog CLI.
Is Apidog free for a small team?
Yes. The free plan supports up to four users and includes spec editing, published interactive docs, smart mocks, and API testing. Beyond four users, the listed price is $9 per user per month.
Export first, redesign later
Use this migration order:
- Export every Apiary project.
- Convert API Blueprint files to OpenAPI.
- Validate converted specs, especially authentication and documentation prose.
- Import OpenAPI into your chosen platform.
- Replace docs URLs, mock URLs, and Dredd checks.
The export and conversion steps have a deadline. Platform evaluation does not.
When you are ready, import the OpenAPI file into Apidog to restore documentation, mocking, and test automation from a single specification.
Top comments (0)