Support OpenAPI specification as a declarative config source
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 1
- Forks
- 0
- Avg merge
- 1h 3m
- Merged PRs (30d)
- 1
Description
Summary
Add an a7 config convert (or similar) command that takes an OpenAPI 3.x specification and produces an a7 declarative configuration file. The adc CLI has the equivalent feature today.
Motivation
Teams that already maintain OpenAPI specs as the source of truth for their HTTP APIs currently have to write a parallel a7 config by hand. Letting them generate a starter config from the OpenAPI doc:
- removes the manual translation step,
- keeps gateway config in sync with the service contract,
- matches what users coming from `adc` already expect.
adc reference
- Library: `adc/libs/converter-openapi/`
- Tests / fixtures: `adc/libs/converter-openapi/test/assets/basic-1.yaml` through `basic-7.yaml` (basic conversion) and `extension-1.yaml` through `extension-12.yaml` (custom `x-*` extension handling)
- Test specs: `adc/libs/converter-openapi/test/basic.spec.ts`, `extension.spec.ts`
Scope sketch
Mapping rules (from adc):
| OpenAPI element | a7 resource |
|---|---|
| `servers` | service with inline upstream (host/port from URL) |
| `paths` + method | route (URI from path, method in `methods`) |
| Path operation `x-adc-route` extensions | route-level overrides (name, plugins, labels) |
| Top-level `x-adc-service` | service-level overrides |
| Component `x-adc-plugins` | plugin attachments |
CLI surface (proposal — open to discussion):
```
a7 config convert --from-openapi spec.yaml -o config.yaml
```
Or as a subcommand of `config`: `a7 config convert openapi spec.yaml`.
Design considerations
- Schema library — Go ecosystem has `getkin/kin-openapi` (most common) and `pb33f/libopenapi`. Pick one that handles 3.0 + 3.1.
- Extension namespace — adc uses `x-adc-`. We could keep that, switch to `x-a7-`, or accept both for compatibility with adc-generated specs.
- Round-trip — is the inverse (`a7 config → OpenAPI`) in scope? adc does not do this; would suggest deferring.
- Validation chain — converted config should round-trip through `a7 config validate` cleanly.
Why deferred
Identified as a parity gap during the adc → a7 test parity audit (see `docs/adc-test-parity-plan.md`). Scope is too large to bundle with the other parity work — needs a dedicated package with its own fixture-driven test suite (the adc equivalent has ~19 fixture files).
Definition of done
- `a7 config convert` (or chosen surface) accepts OpenAPI 3.x YAML/JSON.
- Output passes `a7 config validate`.
- Test coverage equivalent to adc's basic-1..7 + extension-1..12 cases.
- Documented in `docs/`.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/adc-test-parity-plan.md and the existing a7 config command and validation flow. Study adc/libs/converter-openapi/, its basic-1..7 and extension-1..12 fixtures, and basic.spec.ts and extension.spec.ts; done means OpenAPI 3.x YAML/JSON conversion, equivalent coverage, validation success, and documentation in docs/.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, openapi
- Domain
- api, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100