Generating API Specs from DDD Workshop Artifacts with Claude Opus 4.7
In Chapters 5 and 6 of Crafting Great APIs with Domain-Driven Design, Annegret and I describe a small but valuable workflow: use an LLM to turn DDD workshop artifacts into a starting-point API specification. The same recipe works for both OpenAPI (synchronous) and AsyncAPI (asynchronous). The book uses OpenAI ChatGPT 4o and an early Claude model as examples. The recipe still works; the models have moved on.
I redid the experiment in April 2026 with Claude Opus 4.7. For this walkthrough I’ll use the AsyncAPI variant on the Catalog Search bounded context from Chapter 7, the same example in the book, so you can flip to it and follow along. Catalog Search is just the example; the OpenAPI variant of the same workflow, on a synchronous bounded context, is walked through in the book.
The setup
Three inputs, one short system prompt.
System prompt (abbreviated):
You are a specialized AsyncAPI 3.0.0 Generator Assistant. You analyze images of an API Product Canvas and a Visual Glossary, plus a YAML AsyncAPI example as a reference template. Generate a complete, valid AsyncAPI 3.0.0 specification combining all this information. Make reasonable assumptions where the inputs are unclear, and explain your reasoning.
Input 1: API Product Canvas
The API Product Canvas is a one-page workshop artifact that captures the purpose of an API, its consumed and published events, parameters, responses, and success criteria. It is the product view of the API.
For Catalog Search (Figure 7-11 in the book), the canvas lists the published event BookSelected and the consumed events CatalogEntryCreated, CatalogEntryChanged, and CatalogEntryDeleted.
Input 2: Visual Glossary
The Visual Glossary is a workshop artifact, usually a tree of sticky notes, that captures the entities of the bounded context together with their attributes, cardinalities, and relationships, all expressed in the team’s ubiquitous language.
For Catalog Search, it defines CatalogEntry with a catalogIdentifier, an isbn (one of ISBN-10 or ISBN-13), authors (1..*, each with an identifier, name, and givenName), a title, and an optional abstract.
Input 3: AsyncAPI Reference Skeleton
The reference skeleton is a starter AsyncAPI YAML carrying the team’s conventions (security scheme, message headers, naming) so the generated spec stays consistent with the rest of the service catalog. It follows the conventions from the book’s Utilities section, the AsyncSkeleton.yaml from the book’s code samples. Abbreviated:
asyncapi: 3.0.0
info:
title: Skeleton
version: 1.0.0
contact:
name: ...
servers:
production:
host: "events.{your organization}.com:9092"
protocol: "kafka"
security:
- $ref: '#/components/securitySchemes/user-password'
defaultContentType: application/json
channels:
resourceEventIn:
address: "service/resourceIn"
messages:
resourceEventIn:
$ref: '#/components/messages/resourceEventIn'
# resourceEventOut: ...
operations:
resourceEventIn:
action: "receive"
channel:
$ref: "#/channels/resourceEventIn"
# resourceEventOut: { action: send, ... }
components:
messages:
resourceEventIn:
headers:
$ref: '#/components/schemas/MessageHeader'
payload:
$ref: '#/components/schemas/ResourceIn'
schemas:
MessageHeader:
type: object
required: [correlationId, messageId]
properties:
correlationId: { type: string, format: uuid }
messageId: { type: string, format: uuid }
source: { type: string }
# ResourceIn / ResourceOut: define your resource
securitySchemes:
user-password:
type: userPassword
That’s it. Two screenshots and a YAML. No further explanation.
The full Claude conversation is here; the generated AsyncAPI as a standalone Claude artifact is here.
What Anthropic Opus produced
A complete AsyncAPI 3.0.0 file: channels for each event, message schemas, and operations on the produce and consume sides. Cardinalities matched the glossary. The shape was right.
Alongside the spec, Anthropic Opus enumerated the modeling decisions it had taken under uncertainty and asked me to confirm or override each one. That list is what the developer should focus on. The generated spec is a starting point, not a finished deliverable: it still needs to be reviewed by the team and the domain experts before it goes anywhere near a downstream consumer. For example, full field lists that were not modeled in the Visual Glossary, rules on field values, and detailed descriptions are typically still missing. The value of the model is, first and foremost, that it produces the tedious first version, and then helps you in the review process by telling you where to look at design decisions explicitly.
What this changes (and what doesn’t)
The 2025 version of this technique (see Figure 5-44 in the book) was already useful: the model would draft the YAML, you’d review it, and you’d save a few hours. The April 2026 version is qualitatively different. The model now treats the prompt as a design conversation: it produces a draft and a list of the assumptions baked into it.
But fundamentally, not much has changed in this scenario. The DDD process is still where the value is created. The Visual Glossary and the API Product Canvas are doing the work; the model is just transcribing them faithfully. Skip those, and you’ll get generic mush no matter which LLM you use, and it won’t be what business and IT need, since the main value of the full process is aligning different stakeholder views.
The collaborative DDD work between business and IT stakeholders is still the part that creates the value. The model just makes the last mile faster and the review more focused.
A note on AsyncAPI versions
I still used AsyncAPI 3.0.0 for this example, since the template I work from and some of the surrounding tooling still work better with 3.0.0. Keep in mind, though, that 3.1.0 was released in January 2026, see the release notes.
The full method, both for OpenAPI and AsyncAPI, is in Chapters 5 and 6 of Crafting Great APIs with Domain-Driven Design. The book covers the entire process, from identifying business ideas to great APIs:
- 📘 Springer (20% off with APAUT)
- 📦 Amazon
I also walked through this workflow on stage most recently at Spring I/O 2026:
