Skip to content

Commit a0aea88

Browse files
ndrenondreno
committed
Add second blog post: One Gateway, Many Specs
Covers multi-spec compilation, routing conflict detection (E1010), the /__barbacane/specs endpoint, CI/CD integration, and shift-left across service boundaries.
1 parent 7683053 commit a0aea88

1 file changed

Lines changed: 192 additions & 0 deletions

File tree

‎src/content/blog/one-gateway-many-specs.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
title: "One Gateway, Many Specs: How Barbacane Unifies Your API Ecosystem"
3+
description: "Most API tooling assumes one repo, one spec. But microservices don't work that way. Explore how Barbacane's multi-spec compilation merges your OpenAPI and AsyncAPI files into a single, validated artifact."
4+
publishDate: 2026-02-13
5+
author: "Nicolas Dreno"
6+
tags: ["barbacane", "api-gateway", "openapi", "asyncapi", "microservices"]
7+
---
8+
9+
*Most API tooling assumes one repository, one specification. But your architecture doesn't work that way.*
10+
11+
In our [previous article](/blog/beyond-configuration-drift/), we explored how Barbacane eliminates configuration drift by compiling your OpenAPI spec directly into the gateway's runtime artifact. One spec, one `.bca` file, zero drift.
12+
13+
But what happens when your architecture has more than one spec?
14+
15+
---
16+
17+
### The Multi-Spec Reality
18+
19+
In a typical microservices setup, your API surface isn't described by a single file. Whether you're working contract-first or generating specs from code, you end up with multiple specifications:
20+
21+
- A **User Service** with its own `openapi.yaml`
22+
- An **Order Service** with its own `openapi.yaml`
23+
- An **Inventory Service** exposing both REST endpoints and event consumers, described across OpenAPI and AsyncAPI files
24+
- Event schemas scattered across repos
25+
26+
Each file is validated in isolation, deployed independently, and versioned on its own timeline. Single-spec tools can't see across these boundaries, so cross-service mismatches only surface at runtime. The feedback loop is as slow as it gets: write specs, deploy, discover the conflict in production, fix, redeploy.
27+
28+
---
29+
30+
### One Command, Multiple Specs
31+
32+
Barbacane's `compile` command accepts multiple specification files in a single invocation:
33+
34+
```bash
35+
barbacane compile \
36+
-s services/user-service/openapi.yaml \
37+
-s services/order-service/openapi.yaml \
38+
-s services/inventory-service/openapi.yaml \
39+
-s services/inventory-service/asyncapi.yaml \
40+
-m barbacane.yaml \
41+
-o gateway.bca
42+
```
43+
44+
The compiler parses every file (OpenAPI 3.x and AsyncAPI 3.0.x) and merges their routes into a single `.bca` artifact. The output message tells you exactly what you got:
45+
46+
```
47+
compiled 4 spec(s) to gateway.bca (23 routes, 5 plugin(s) bundled)
48+
```
49+
50+
One artifact. One routing table. One deployment.
51+
52+
---
53+
54+
### What Multi-Spec Compilation Actually Does
55+
56+
When you pass multiple specs, the compiler:
57+
58+
1. **Parses each file independently.** OpenAPI and AsyncAPI specs are each validated against their respective standards.
59+
60+
2. **Merges routes into a unified routing table.** All operations from all specs end up in a single `routes.json` inside the `.bca` artifact. The gateway doesn't care which file a route came from; it serves them all.
61+
62+
3. **Detects routing conflicts.** If two specs define the same path and method combination (e.g., both declare `GET /users/{id}`), compilation fails with error `E1010`. This is a hard gate: you cannot produce an artifact with ambiguous routing.
63+
64+
4. **Bundles everything together.** WASM plugins, dispatcher configurations, and the original source specs are all packaged into the artifact. The source specs remain accessible at `/__barbacane/specs` for documentation and debugging.
65+
66+
This isn't magic. It's the same compilation pipeline applied across multiple input files. But the practical impact is a meaningful **shift left**: routing conflicts that would previously surface as mysterious 404s or wrong-handler bugs in production now fail your build.
67+
68+
---
69+
70+
### Specs Stay Accessible at Runtime
71+
72+
Compilation merges routes, but the original source specs aren't thrown away. They're embedded in the `.bca` artifact and served by the gateway at `/__barbacane/specs`:
73+
74+
```
75+
GET /__barbacane/specs
76+
```
77+
78+
This returns an index of every spec that was compiled into the running artifact, with links to the full OpenAPI and AsyncAPI documents. The served specs are stripped of Barbacane-specific extensions (`x-barbacane-*`), so what your API consumers and documentation tools see is clean, standard OpenAPI and AsyncAPI with no vendor-specific noise. And because these are the exact specs that were compiled, they can't drift from what the gateway is actually running.
79+
80+
No separate spec hosting. No stale docs. The gateway *is* the documentation server.
81+
82+
---
83+
84+
### A Practical Example
85+
86+
Consider an e-commerce platform with four services:
87+
88+
```
89+
User Service → openapi.yaml
90+
Order Service → openapi.yaml
91+
Inventory Service → openapi.yaml + asyncapi.yaml
92+
Notification Svc → asyncapi.yaml
93+
```
94+
95+
Without multi-spec compilation, you'd deploy each service's gateway configuration independently, trusting that teams coordinated their path prefixes and schema versions. With Barbacane:
96+
97+
```bash
98+
barbacane compile \
99+
-s services/user-service/openapi.yaml \
100+
-s services/order-service/openapi.yaml \
101+
-s services/inventory-service/openapi.yaml \
102+
-s services/inventory-service/asyncapi.yaml \
103+
-s services/notification-service/asyncapi.yaml \
104+
-m barbacane.yaml \
105+
-o gateway.bca
106+
```
107+
108+
If the Order Service accidentally defines a route that collides with the User Service, compilation fails. You find out in seconds, not after a deploy.
109+
110+
---
111+
112+
### CI/CD Integration
113+
114+
Multi-spec compilation fits naturally into a CI gate. Block merges to `main` if the combined specs don't compile cleanly:
115+
116+
```yaml
117+
# .github/workflows/validate-contracts.yml
118+
jobs:
119+
validate:
120+
runs-on: ubuntu-latest
121+
steps:
122+
- uses: actions/checkout@v4
123+
- name: Compile gateway artifact
124+
run: |
125+
barbacane compile \
126+
-s services/user-service/openapi.yaml \
127+
-s services/order-service/openapi.yaml \
128+
-s services/inventory-service/openapi.yaml \
129+
-s services/inventory-service/asyncapi.yaml \
130+
-m barbacane.yaml \
131+
-o gateway.bca
132+
```
133+
134+
A non-zero exit code (1 for validation failures, 2 for manifest errors) blocks the pipeline. No ambiguous warnings: either the specs compile together, or they don't.
135+
136+
---
137+
138+
### Progressive Adoption
139+
140+
You don't have to compile everything at once. Start with your most critical services and expand:
141+
142+
```bash
143+
# Start with two services
144+
barbacane compile \
145+
-s user-service/openapi.yaml \
146+
-s auth-service/openapi.yaml \
147+
-m barbacane.yaml \
148+
-o gateway.bca
149+
150+
# Later, add event-driven services
151+
barbacane compile \
152+
-s user-service/openapi.yaml \
153+
-s auth-service/openapi.yaml \
154+
-s order-service/openapi.yaml \
155+
-s order-service/asyncapi.yaml \
156+
-m barbacane.yaml \
157+
-o gateway.bca
158+
```
159+
160+
Each additional spec increases the surface area of conflict detection. The more specs you compile together, the more mismatches you catch before deployment.
161+
162+
---
163+
164+
### Strengths and Limitations
165+
166+
Multi-spec compilation extends the "compile, don't configure" philosophy across service boundaries, but it's worth understanding what it does and doesn't do today.
167+
168+
**What it catches:**
169+
- Routing conflicts (duplicate path + method across specs)
170+
- Spec-level validation errors (malformed OpenAPI/AsyncAPI)
171+
- Missing plugin or dispatcher declarations
172+
173+
**What it doesn't do (yet):**
174+
- Cross-spec schema validation (e.g., verifying that an `Order` object is consistent between two specs)
175+
- Breaking change detection between spec versions
176+
- Dependency graph analysis between services
177+
178+
These are real limitations. Multi-spec compilation today is primarily about *route-level unification and conflict detection*, not deep semantic analysis across your API ecosystem. For schema consistency, you'll still need complementary tooling or careful code review.
179+
180+
---
181+
182+
### Shifting Left Across Service Boundaries
183+
184+
The idea behind "shift left" is simple: catch problems earlier in the development lifecycle, when they're cheapest to fix. Linters shift left on code quality. Type systems shift left on correctness. Multi-spec compilation shifts left on *cross-service integration*.
185+
186+
In our [previous article](/blog/beyond-configuration-drift/), we showed how Barbacane shifts gateway configuration left by compiling the spec into the runtime artifact. Multi-spec compilation takes this further: instead of discovering that two services disagree on routing after deployment, you discover it at compile time, in CI, on a pull request.
187+
188+
It's not a silver bullet. Cross-service consistency is a hard problem, and route-level conflict detection is just one piece of the puzzle. But it's a piece that most gateway tooling doesn't offer at all, and one that pays off immediately in any multi-service architecture. The earlier you catch a conflict, the less it costs.
189+
190+
---
191+
192+
*Barbacane is open source (Apache 2.0) and available at [github.com/barbacane-dev/barbacane](https://github.com/barbacane-dev/barbacane). Check the [documentation](https://docs.barbacane.dev/) for the full CLI reference and getting started guide.*

0 commit comments

Comments
 (0)