Im August 2025 habe ich eine ereignisorientierte API in TypeSpec modelliert. Kafka-Topics, MQTT-Muster, WebSocket-Channels — das übliche Chaos, aber typisiert. Ich schrieb die Definitionen, öffnete die Compile-Ziele, und blieb hängen.
TypeSpec hat einen offiziellen OpenAPI-Emitter. Es hat einen offiziellen JSON-Schema-Emitter. Für AsyncAPI — die Spezifikationssprache für genau die Systeme, die ich da beschrieb — stand auf der Zieliste: nichts.
Ich habe gewartet
Ich ging davon aus, dass jemand die Lücke schließen würde. Die AsyncAPI-Initiative pflegt Emitter für andere Quellformate. Microsoft pflegt die TypeSpec-Toolchain. Zwei Organisationen, ein offensichtlich fehlendes Stück dazwischen. Das würde jemand bauen.
Monate vergingen. Die Community-Option tsp-asyncapi existierte — aber als ich sie im August 2026 prüfte, emittierte sie AsyncAPI 3.0, unterstützte 13 Protokolle mit handgeschriebenen Bindings und verifizierte sich mit 15 Property-Tests. AsyncAPI 3.1 war die ganze Zeit schon draußen. Die Lücke blieb offen.
Also baute ich typespec-asyncapi.
Eine Entscheidung hat den Unterschied gemacht
Ich wollte keine 22 Protokoll-Bindings von Hand schreiben. Handgeschriebene Bindings driften ein Jahr später exakt von der Spezifikation weg — die Spezifikation bewegt sich, das Binding bleibt, und jeder Konsument erbt die Differenz.
Deshalb enthält der Emitter keine Protokoll-Bindings. Er generiert sie zur Build-Zeit aus @asyncapi/specs — den offiziellen maschinenlesbaren AsyncAPI-Spezifikationen. Wenn AsyncAPI eine Binding-Änderung veröffentlicht, baue ich neu und der Emitter spricht den neuen Dialekt. Die Quelle der Wahrheit dafür, was ein Kafka-Binding enthält, ist dieselbe Datei, die auch das AsyncAPI-Tooling liest.
Du schreibst das:
import "@lars-artmann/typespec-asyncapi";
using TypeSpec.AsyncAPI;
namespace MyAPI;
model Event {
id: string;
timestamp: utcDateTime;
}
@channel("events")
op publishEvent(): Event;npx tsp compile api.tsp ausführen, und du bekommst ein validiertes AsyncAPI-3.1-Dokument — Channels, Operationen, Messages, Schemas, alles korrekt referenziert, als YAML oder JSON.
270+ Tests gegen das offizielle Schema
Das ist der Teil, der mir am meisten bedeutet. Jedes Dokument, das der Emitter produziert, wird bei jedem Build mit AJV gegen das offizielle AsyncAPI-3.1.0-JSON-Schema validiert — über eine Compliance-Suite von mehr als 270 Tests. Nicht im Review angeguckt. Nicht stichprobenartig geprüft.
Ein Generator, der fast-gültige Specs emittiert, ist schlimmer als kein Generator, weil fast-gültig im schlimmsten Moment Downstream kaputtgeht — im Codegenerator, im Dokumentationsportal, in einem Vertragstest, dem jemand vertraut hat. Der Build ist rot, sobald ein Output-Byte falsch ist, und das ist der einzige Ort, an dem ich es erfahren will.
Diese Suite hat echte Bugs im Emitter gefunden. Sie hat auch Fälle gefunden, in denen meine Annahme über die AsyncAPI-Form falsch war und das Schema widersprach. Beides sind meine. Genau deshalb prüft das Gerät sie.
Wo es steht
Die aktuell veröffentlichte Version ist 0.3.0-beta.1. Sie ist pre-1.0: Decorator-Signaturen und Emitter-Optionen können sich vor Abschluss der Roadmap noch ändern. Wenn du AsyncAPI-2.x-Output brauchst, ist das nicht dein Werkzeug — es zielt bewusst auf 3.x.
Adoption, Stand der 30 Tage bis zum 11. September 2026: npm zählte 663 Downloads von @lars-artmann/typespec-asyncapi. Das GitHub-Repo hat fünfzehn Sterne. Die Zahlen zeigen dir, wo die Zielgruppe von Spec-Tooling wirklich ist — und einer der Konsumenten betreibt es in Produktion bei der Swiss Post.
Fünfzehn Sterne, echter Produktions-Traffic. Diesen Deal mache ich jedes Mal.
Probiere es mit deiner eigenen Spec
npm install @lars-artmann/typespec-asyncapitspconfig.yaml auf den Emitter zeigen, kompilieren, und den Output gegen das prüfen, was deine Event-Infrastruktur wirklich tut. Die Dokumentation — inklusive der vollständigen Decorator-Referenz für Channels, Operationen, Replies, Correlations und Protokoll-Bindings — liegt auf typespec-asyncapi.lars.software.
Wenn du ereignisorientierte APIs pflegst und deine AsyncAPI-Dokumente handeditiertes YAML sind, ist das der Ausweg. Das System einmal typisieren, die Spec generieren, den Schema-Validator die Linie halten lassen.