O Apiary está sendo desativado. A Oracle publicou um comunicado sobre o término do suporte ao Apiary, e reportagens do setor indicam o encerramento do serviço hospedado por volta de setembro de 2026. O site ainda carrega, mas o caminho já estava definido: a Oracle adquiriu o Apiary em janeiro de 2017, descontinuou planos pagos em 2018 e deixou Dredd e Gavel arquivados. Se sua documentação ainda está em apiary.io, trate isso como uma migração com prazo, não como uma avaliação opcional.
A alternativa mais completa é o Apidog: ele cobre edição design-first, documentação hospedada, mocks e adiciona testes automatizados, validação orientada por especificação e integração com CI. O ponto importante para projetos antigos é que o Apidog não importa API Blueprint diretamente. Portanto, APIs em Blueprint precisam passar por uma conversão única para OpenAPI antes da importação.
O que está acontecendo com o Apiary
Fundado em 2011, o Apiary popularizou o fluxo de trabalho de API design-first. Ele introduziu o API Blueprint, ofereceu documentação em três colunas, mocks hospedados, sincronização com GitHub e ferramentas de teste de contrato como Dredd e Gavel.
Após a aquisição pela Oracle em 2017, o produto entrou em manutenção limitada. Os planos pagos foram encerrados em 2018, novos recursos deixaram de chegar e Dredd e Gavel foram arquivados. O serviço hospedado deve ser encerrado por volta de setembro de 2026.
O Bump.sh, que também mantém um guia de migração do Apiary, resume bem a prioridade: exporte suas especificações enquanto ainda há como fazê-lo.
Na prática, isso gera duas tarefas imediatas:
- Exportar descrições, documentação e configurações que existam apenas no Apiary.
- Converter projetos API Blueprint para OpenAPI, o formato de destino mais sustentável.
O que precisa ser substituído
Antes de escolher a ferramenta de destino, mapeie os recursos que sua equipe usava no Apiary:
- Editor design-first: criação de API Blueprint ou OpenAPI no navegador.
-
Documentação hospedada: referência interativa em uma URL
apiary.io. - Servidor mock: endpoints que respondiam com os exemplos definidos na especificação.
- Sincronização com GitHub: especificação versionada no repositório.
- Testes de contrato: validação da implementação contra a especificação com Dredd.
O último item merece atenção: Dredd está arquivado. Para uma substituição prática, veja como validar sua API contra a especificação sem o Dredd.
Por que usar o Apidog
O Apidog reúne design, documentação, mocking, depuração e testes automatizados em torno de uma única especificação OpenAPI.
Para uma migração do Apiary, o fluxo é direto:
Defina a API em OpenAPI.
Use o editor visual ou o editor de código para manter endpoints, schemas e exemplos em uma fonte de verdade.Publique documentação interativa.
A documentação pode incluir console de teste, versionamento e domínio personalizado. Isso evita depender novamente de uma URL hospedada por uma plataforma que pode ser descontinuada.Restaure os mocks.
O smart mock gera respostas a partir dos schemas. Quando for necessário retornar dados específicos, adicione regras de mock personalizadas.Substitua Dredd por cenários de teste.
Crie solicitações reais contra sua implementação, valide respostas com base no schema OpenAPI e execute a suíte em CI usando o Apidog CLI.
O Apidog também publica documentação com um servidor MCP para que agentes de IA possam consultar a especificação. Veja o que é o Apidog MCP Server.
Migração do Apiary passo a passo
O Apidog importa OpenAPI 3.x, Swagger 2.0, coleções Postman, HAR, RAML, JMeter, apiDoc, I/O Docs, WADL e Google Discovery, conforme a documentação de importação.
API Blueprint não está na lista. Portanto, a migração de projetos Blueprint tem uma etapa adicional: converter para OpenAPI.
1. Exporte tudo do Apiary agora
Para cada projeto:
- Baixe a descrição da API pelo editor do Apiary.
- Se houver sincronização com GitHub, confirme se o repositório contém a versão mais recente.
- Exporte textos de documentação que não estejam presentes na especificação.
- Registre URLs de documentação e mocks que consumidores externos ainda usam.
Projetos mais recentes criados em OpenAPI 3.0 podem pular a conversão e seguir diretamente para a importação.
Faça esta etapa antes de redesenhar documentação, reorganizar endpoints ou trocar o processo de testes. A exportação é a parte que tem prazo.
2. Converta API Blueprint para OpenAPI
Para projetos em API Blueprint, use um conversor como:
-
api-spec-converter(LucyBot), com suporte direto para API Blueprint. -
apib2swagger, focado em converter Blueprint para Swagger/OpenAPI. -
openapi-format, opcionalmente, para normalizar o resultado e atualizar o arquivo para OpenAPI 3.1.
Exemplo de fluxo de validação após a conversão:
# Converta o arquivo API Blueprint para OpenAPI
api-spec-converter api.md --from api_blueprint --to openapi_3 --syntax yaml > openapi.yaml
# Normalize ou formate a saída, se necessário
openapi-format openapi.yaml --output openapi-formatted.yaml
# Execute seu linter OpenAPI
vacuum lint openapi-formatted.yaml
Revise manualmente principalmente:
- Autenticação: API Blueprint não modelava esquemas de autenticação formalmente, então conversores podem não recuperar todos os detalhes.
- Documentação em Markdown: textos fora das descrições de endpoints podem exigir reposicionamento.
- Exemplos de payload: confirme se exemplos e tipos de conteúdo foram convertidos corretamente.
- Códigos de resposta: valide respostas de erro e schemas associados.
Para a maioria das APIs, a conversão é uma tarefa de horas, não de semanas.
3. Importe o OpenAPI no Apidog
No Apidog:
- Abra Configurações do Projeto.
- Selecione Importação Manual.
- Escolha o arquivo OpenAPI ou informe uma URL.
- Revise endpoints, schemas, exemplos e agrupamentos importados.
- Publique a documentação e copie a URL do mock.
Após a importação, a referência da API fica disponível e cada endpoint pode usar o mock baseado em schema.
4. Recrie integrações e testes
Finalize a migração com as partes operacionais:
- Configure um domínio personalizado para a documentação publicada.
- Atualize links de documentação usados por clientes e equipes internas.
- Envie a nova URL base do mock para consumidores da API.
- Recrie verificações Dredd como cenários de teste.
- Execute testes localmente e no CI com o CLI.
- Mantenha o arquivo OpenAPI no Git como fonte de verdade.
Um cenário básico de teste deve validar ao menos:
1. Enviar uma requisição para a implementação real.
2. Verificar o status HTTP.
3. Validar o corpo contra o schema OpenAPI.
4. Validar campos críticos com asserções.
5. Executar o mesmo cenário no pipeline de CI.
Uma API única normalmente pode ser migrada em uma tarde. Para várias APIs Blueprint, o maior esforço tende a ser a revisão de autenticação e documentação manual.
Apiary vs. Apidog
| Recurso | Apiary (hoje) | Apidog |
|---|---|---|
| Futuro | Encerrando; fim do serviço esperado por volta de setembro de 2026 | Ativamente desenvolvido |
| Formato da especificação | API Blueprint, depois OpenAPI 3.0 | OpenAPI 3.x, com importação de Swagger 2.0 |
| Editor | Editor de especificação | Editor visual e de código |
| Documentação hospedada | Sim, em URLs apiary.io | Sim, com domínio personalizado, versionamento e console de teste |
| Servidor mock | Reproduz exemplos escritos | Smart mocks baseados em schema e regras personalizadas |
| Testes de contrato | Dredd, arquivado | Cenários de teste, validação de schema e CI via CLI |
| Suítes automatizadas | Não | Sim, incluindo cenários visuais e orientados por dados |
| Sincronização com GitHub | Sim | Importação ou sincronização por arquivo/URL e versionamento por branch |
| Preço | Gratuito; planos pagos encerrados em 2018 | Gratuito para até 4 usuários; depois US$ 9 por usuário/mês |
| Exportação | API Blueprint e OpenAPI | OpenAPI, Markdown e HTML |
Quanto custa substituir uma ferramenta gratuita
O Apiary era gratuito em sua fase final. Portanto, compare o custo anual apenas se sua equipe precisa de documentação, mocks, testes e colaboração no mesmo produto.
| Tamanho da equipe | Apidog por ano | SwaggerHub Team por ano | ReadMe Pro por ano |
|---|---|---|---|
| 3 pessoas | US$ 0 (plano gratuito) | US$ 1.240 | US$ 3.000 |
| 5 pessoas | US$ 540 | US$ 2.066 | US$ 3.000 |
| 10 pessoas | US$ 1.080 | US$ 4.133 | US$ 3.000 |
| 25 pessoas | US$ 2.700 | US$ 10.332 | US$ 3.000 |
Se você precisa somente renderizar uma especificação, ferramentas focadas em documentação também podem ter planos gratuitos. A comparação acima faz sentido quando você quer substituir o pacote completo do Apiary: design, documentação, mocks, testes e colaboração.
Quando o Apidog não é a melhor opção
O Apiary não é uma opção de longo prazo, mas o Apidog também não é o único destino possível.
Você precisa apenas de documentação hospedada.
Se design e testes acontecem em outro lugar, uma ferramenta focada em documentação como Bump.sh pode ser suficiente. APIs em Blueprint ainda precisam ser convertidas para OpenAPI.Sua organização já usa SmartBear.
SwaggerHub é uma alternativa próxima ao modelo de registro hospedado de especificações. Compare custo por assento e limites de execução. Veja a melhor alternativa ao SwaggerHub.Seu foco principal é governança de design.
Para equipes grandes de plataforma com guias de estilo e governança mais profundos, Stoplight pode ser relevante. Compare antes em a melhor alternativa ao Stoplight.Você quer manter API Blueprint.
Evite prolongar essa dependência. O ecossistema está sem manutenção e a migração para OpenAPI será necessária independentemente da ferramenta escolhida. O guia de API Blueprint pode servir como referência histórica.
Perguntas frequentes
Quando exatamente o Apiary será desativado?
A Oracle anunciou o término do suporte ao Apiary, e reportagens do setor apontam para o encerramento do serviço hospedado por volta de setembro de 2026. Exporte seus dados agora, enquanto o serviço ainda permite exportações.
O Apidog importa API Blueprint diretamente?
Não. Converta o Blueprint para OpenAPI primeiro usando ferramentas como api-spec-converter ou apib2swagger. Depois, importe o arquivo OpenAPI e revise manualmente autenticação, exemplos e conteúdo documental.
O que substitui o servidor mock do Apiary?
O mock integrado do Apidog. Ele pode gerar respostas com base nos schemas da especificação e aceitar regras personalizadas para cenários que exigem respostas determinísticas.
O que substitui Dredd para testes de contrato?
Cenários de teste automatizados que enviam requisições reais à implementação e validam as respostas contra a especificação OpenAPI. O Apidog CLI permite executar esses testes no CI.
O Apidog é gratuito para equipes pequenas?
Sim. O plano gratuito cobre até 4 usuários com editor de especificações, documentação publicada, servidor mock e testes de API. Acima desse limite, o preço informado é de US$ 9 por usuário/mês.
Exporte primeiro, redesenhe depois
A ordem correta é:
- Exporte do Apiary.
- Converta API Blueprint para OpenAPI.
- Valide e corrija a especificação.
- Importe no destino.
- Reconstrua documentação, mocks e testes.
Não comece redesenhando sua API. Primeiro garanta que a especificação e a documentação saíram do Apiary. Depois, importe o OpenAPI no Apidog para recuperar documentação, mocks e testes em uma plataforma mantida.
Baixe o Apidog ou comece pelo navegador.
Top comments (0)