Die beste Alternative zu Apiary

Apiary wird eingestellt. Oracle hat eine Ankündigung zur Beendigung des Apiary-Supports veröffentlicht; Berichte aus dem API-Tooling-Bereich erwarten das Ende des gehosteten Dienstes etwa im September 2026. Die Website ist aktuell noch erreichbar, aber die Entwicklung ist seit Jahren praktisch beendet: Oracle übernahm Apiary im Januar 2017, stellte kostenpflichtige Pläne 2018 ein und ließ Tools wie Dredd und Gavel archivieren. Liegt Ihre API-Dokumentation auf apiary.io, sollten Sie jetzt exportieren und migrieren.

Apidog noch heute ausprobieren

Die direkte Empfehlung lautet: Apidog deckt die zentralen Apiary-Workflows ab—spezifikationsgetriebenes Design, gehostete interaktive Dokumentation und Mock-Server—und ergänzt automatisierte API-Tests, Schemavalidierung und CI-Integration. Der wichtigste Migrationspunkt: API Blueprint lässt sich nicht direkt importieren. Blueprint-Projekte müssen deshalb einmalig nach OpenAPI konvertiert werden.

Dieser Artikel zeigt den praktischen Migrationspfad und ordnet Alternativen ein.

Was tatsächlich mit Apiary passiert

Apiary wurde 2011 gegründet und prägte den Design-First-Workflow für APIs. Das Produkt brachte API Blueprint hervor, ein Markdown-basiertes Beschreibungsformat aus der Zeit vor OpenAPI. Außerdem bot Apiary gehostete Dokumentation, Mock-Server, GitHub-Synchronisierung sowie die Open-Source-Tools Dredd und Gavel für Vertragstests.

Nach der Oracle-Übernahme im Januar 2017 wurde es ruhig: Kostenpflichtige Tarife verschwanden 2018, neue Funktionen blieben aus, und Dredd sowie Gavel wurden archiviert. Mit der formalen Support-Beendigung ist jetzt klar: Der gehostete Dienst wird voraussichtlich um September 2026 eingestellt. Bump.sh formuliert es in seinem Abschiedsbeitrag eindeutig: Exportieren Sie Ihre API-Beschreibungen vor der Abschaltung.

Daraus folgen zwei konkrete Aufgaben:

1. Exportieren Sie alles, was nur in Apiary liegt: Spezifikationen, Dokumentationstexte und Teamkonfiguration.
2. Migrieren Sie von API Blueprint nach OpenAPI: Für Blueprint gibt es kein aktiv gepflegtes Nachfolge-Ökosystem. OpenAPI ist das sinnvolle Zielformat.

Was Sie ersetzen müssen

Erfassen Sie vor der Migration, welche Apiary-Funktionen Ihr Team nutzt:

• Design-First-Spezifikationseditor: API Blueprint oder OpenAPI 3.0 im Browser bearbeiten.
• Gehostete interaktive Dokumentation: Referenzdokumentation mit Beispielanfragen unter einer apiary.io-URL.
• Mock-Server: Gehostete Mock-Endpunkte auf Basis der Spezifikation und Beispiele.
• GitHub-Synchronisierung: Spezifikationen im Repository verwalten und synchronisieren.
• Vertragstests mit Dredd: Spezifikation gegen eine reale API-Implementierung prüfen. Dredd ist archiviert; eine Alternative beschreibt der Artikel API ohne Dredd gegen ihre Spezifikation validieren.

Suchen Sie daher nicht nur nach einem Dokumentationsrenderer. Das Ziel sollte Design, Dokumentation, Mocking und Validierung in einem gepflegten Workflow abdecken.

Die Antwort: Apidog

Apidog ist eine API-Entwicklungsplattform mit Funktionen für Design, Dokumentation, Mocking, Debugging und automatisierte Tests.

Für eine Apiary-Migration sind insbesondere diese Punkte relevant:

1. Spezifikationsgetriebener Workflow
   
   Apidog bietet einen visuellen Editor und einen Code-Editor für OpenAPI 3.x. Endpunkte, Schemas und Beispiele werden einmal definiert; Dokumentation, Mocks und Tests basieren auf derselben Spezifikation.

2. Gehostete, interaktive Dokumentation
   
   Veröffentlichte Dokumentationen enthalten eine „Try it“-Konsole, Versionierung und Unterstützung für benutzerdefinierte Domains. So bleibt Ihre Docs-URL unabhängig von einer Plattform.

3. Schema-basierte Mocks
   
   Apiarys Mock-Server spielte primär definierte Beispiele aus. Apidogs Smart Mock kann Antworten aus Schemas generieren und zusätzlich benutzerdefinierte Regeln verwenden.

4. Dredd-Ersatz für Vertragstests
   
   Testszenarien senden reale Requests an Ihre Implementierung und validieren Responses gegen die Spezifikation. Assertions, datengesteuerte Testfälle und CI-Läufe sind über die Apidog CLI möglich. Dokumentationen können zudem neben einem MCP-Server veröffentlicht werden; Details finden Sie unter Was ist der Apidog MCP Server?.

Migration von Apiary: Schritt für Schritt

Apidog importiert laut Import-Dokumentation OpenAPI, Swagger 2.0, Postman-Collections, HAR, RAML, JMeter, apiDoc, I/O Docs, WADL und Google Discovery. API Blueprint gehört nicht dazu.

Für Blueprint-Projekte lautet der Migrationspfad daher:

Apiary exportieren
  → API Blueprint nach OpenAPI konvertieren
  → OpenAPI validieren
  → in Apidog importieren
  → Docs, Mocks und Tests veröffentlichen

1. Alles aus Apiary exportieren

Exportieren Sie für jedes Projekt die API-Beschreibung aus dem Apiary-Editor.

Wenn GitHub-Synchronisierung aktiv ist:

• Prüfen Sie, ob das Repository aktuell ist.
• Verwenden Sie die Datei im Repository als Quelle der Wahrheit.
• Sichern Sie zusätzlich den letzten Stand aus Apiary.

Apiary-Projekte, die bereits OpenAPI 3.0 verwenden, können den Konvertierungsschritt überspringen.

Exportieren Sie zuerst. Die Abschaltung betrifft genau den Teil Ihrer Migration, den Sie später nicht mehr nachholen können.

2. API Blueprint nach OpenAPI konvertieren

Verwenden Sie einen Konverter wie:

• api-spec-converter von LucyBot
• apib2swagger
• openapi-format zum anschließenden Normalisieren oder Aktualisieren auf OpenAPI 3.1

Beispielhafter Ablauf:

# Blueprint in eine OpenAPI-/Swagger-Datei konvertieren
api-spec-converter api.apib --from api_blueprint --to openapi_3 --syntax yaml > openapi.yaml

# Optional: Ausgabe formatieren oder normalisieren
openapi-format openapi.yaml --output openapi.normalized.yaml

Validieren Sie die erzeugte Datei anschließend mit Ihrem OpenAPI-Linter, beispielsweise vacuum.

Prüfen Sie besonders diese zwei Bereiche manuell:

• Authentifizierung: API Blueprint modelliert Authentifizierung nicht so formal wie OpenAPI. Konverter können Security Schemes daher nicht vollständig rekonstruieren.
• Freitext-Dokumentation: Inhalte aus Blueprint-Markdown können außerhalb von Endpunktbeschreibungen liegen und müssen eventuell neu zugeordnet werden.

Für eine typische API ist das eher eine Aufgabe von etwa einer Stunde als von einer Woche.

3. OpenAPI in Apidog importieren

Importieren Sie die konvertierte Datei in den Projekteinstellungen über den manuellen Import oder per URL.

Nach dem Import sollten Sie prüfen:

• Sind alle Pfade und HTTP-Methoden vorhanden?
• Wurden Request- und Response-Schemas korrekt übernommen?
• Sind Beispiele und Statuscodes vollständig?
• Wurden Security Schemes richtig abgebildet?
• Stimmen Server-URLs und Umgebungsvariablen?

Danach stehen Referenzdokumentation und Smart Mock für die importierten Endpunkte bereit.

4. Dokumentation, Tests und URLs umstellen

Bauen Sie die Teile neu auf, die an Apiary gekoppelt waren:

1. Veröffentlichen Sie die Dokumentation unter einer benutzerdefinierten Domain.
2. Ersetzen Sie Dredd-Prüfungen durch Testszenarien mit echten Requests und Schemavalidierung.
3. Führen Sie Tests lokal und in CI über die CLI aus.
4. Informieren Sie API-Konsumenten über neue Docs- und Mock-Basis-URLs.
5. Aktualisieren Sie Links in READMEs, SDKs, Portalen und internen Wikis.

Ein einzelnes API-Projekt kann inklusive Konvertierung an einem Nachmittag migriert werden. Bei mehreren Blueprint-APIs liegt der Hauptaufwand meist in der manuellen Prüfung von Authentifizierung und Dokumentation.

Apiary vs. Apidog auf einen Blick

	Apiary (heute)	Apidog
Zukunft	Wird eingestellt; Dienstende voraussichtlich um September 2026	Aktiv entwickelt
Spezifikationsformat	API Blueprint, später OpenAPI 3.0	OpenAPI 3.x, Swagger-2.0-Import, visueller und Code-Editor
Gehostete Dokumente	Ja, unter apiary.io-URLs	Ja, mit benutzerdefinierter Domain, Versionierung und Try-it-Konsole
Mock-Server	Spielt definierte Beispiele ab	Schema-basierte Smart Mocks und benutzerdefinierte Regeln
Vertragstests	Dredd, archiviert	Testszenarien, Schemavalidierung und CI über CLI
Automatisierte Testsuiten	Nein	Ja, visuelle und datengesteuerte Szenarien
GitHub-Synchronisierung	Ja	Spezifikationsimport bzw. -synchronisierung per URL oder Datei; branch-basierte Versionierung
Preis	Kostenlos; kostenpflichtige Pläne seit 2018 eingestellt	Kostenlos für bis zu 4 Benutzer, danach $9 pro Benutzer/Monat
Exportpfad	API Blueprint oder OpenAPI	OpenAPI-, Markdown- und HTML-Exporte

Was der Ersatz eines kostenlosen Tools kostet

Apiarys kostenloser Preis war ein großer Vorteil. Für Teams, die Mocking, Tests und Zusammenarbeit benötigen, ergibt sich laut den genannten Listenpreisen folgender Vergleich:

Teamgröße	Apidog pro Jahr	SwaggerHub Team pro Jahr	ReadMe Pro pro Jahr
3 Personen	$0, kostenloser Plan	$1.240	$3.000
5 Personen	$540	$2.066	$3.000
10 Personen	$1.080	$4.133	$3.000
25 Personen	$2.700	$10.332	$3.000

Wenn Sie ausschließlich eine Spezifikation rendern möchten, können reine Dokumentationstools mit kostenlosen Tarifen ausreichen. Die Tabelle wird relevant, sobald Sie die Kombination aus Dokumentation, Mock-Server, Tests und Team-Workflow benötigen.

Wenn Apidog nicht die richtige Wahl ist

Nicht jede Migration hat dieselben Anforderungen.

• Sie benötigen nur Dokumentationsrendering.
  
  Wenn Spezifikation und Tests bereits anderswo verwaltet werden, kann ein Docs-First-Tool wie Bump.sh passen. Auch dort müssen Sie API Blueprint zuerst nach OpenAPI konvertieren.

• Sie standardisieren auf SmartBear.
  
  SwaggerHub ist ein naheliegendes Ziel für Teams, die im SmartBear-Ökosystem arbeiten. Berücksichtigen Sie Kosten pro Benutzer und getaktete Testausführungen. Details finden Sie in der besten SwaggerHub-Alternative.

• Sie brauchen umfangreiche API-Governance.
  
  Für große Plattformteams mit starkem Fokus auf Styleguides und Governance kann Stoplight relevant sein. Vergleichen Sie die Optionen in der besten Stoplight-Alternative.

• Sie möchten API Blueprint behalten.
  
  Das ist verständlich, aber nicht empfehlenswert. Das Tooling wird nicht mehr aktiv gepflegt, Apiary wird abgeschaltet und OpenAPI ist der etablierte Standard. Konvertieren Sie einmal und verwalten Sie die Spezifikation künftig als OpenAPI. Der Leitfaden zu API Blueprint bleibt als Hintergrundwissen nützlich.

Häufig gestellte Fragen

Wann genau wird Apiary abgeschaltet?

Oracle hat die Beendigung des Apiary-Supports angekündigt. Berichte von API-Tooling-Anbietern gehen davon aus, dass der gehostete Dienst etwa im September 2026 endet. Die sichere Vorgehensweise: jetzt exportieren.

Kann Apidog API-Blueprint-Dateien direkt importieren?

Nein. Apidog importiert OpenAPI/Swagger, Postman, HAR, RAML, JMeter, apiDoc, I/O Docs, WADL und Google Discovery. Konvertieren Sie API Blueprint zuerst mit api-spec-converter oder apib2swagger nach OpenAPI und prüfen Sie insbesondere die Authentifizierungsschemata manuell.

Was ersetzt den Apiary Mock-Server?

Der integrierte Smart Mock-Server von Apidog. Während Apiary definierte Beispiele ausspielte, kann Apidog Antworten aus Schemas generieren. Für spezielle Fälle lassen sich benutzerdefinierte Mock-Regeln definieren.

Was ersetzt Dredd für Vertragstests?

Automatisierte Testszenarien in Apidog: Sie senden reale Requests an Ihre Implementierung, validieren Responses gegen die Spezifikation und können Assertions sowie CI-Ausführung über die CLI verwenden.

Ist Apidog für kleine Teams kostenlos?

Ja. Der kostenlose Plan deckt bis zu vier Benutzer ab, einschließlich Spezifikationseditoren, veröffentlichter interaktiver Dokumentation, Smart Mock-Server und API-Tests. Ab dem fünften Benutzer beträgt der Preis $9 pro Benutzer und Monat.

Heute exportieren, später optimieren

Die richtige Reihenfolge ist:

1. Apiary-Projekte exportieren.
2. API Blueprint nach OpenAPI konvertieren.
3. OpenAPI validieren.
4. Zielplattform auswählen und importieren.
5. Dokumentations-, Mock- und CI-URLs umstellen.

Die ersten beiden Schritte sind fristgebunden; die Tool-Auswahl danach nicht. Importieren Sie Ihre OpenAPI-Datei in Apidog, richten Sie Dokumentation, Mocking und Tests ein und vermeiden Sie, dass Ihre API-Dokumentation mit Apiary verschwindet.