Support OpenAPI specification as a declarative config source
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 35/100
Hướng nghiên cứu
Bắt đầu với docs/adc-test-parity-plan.md cùng a7 config command và luồng validation hiện có. Nghiên cứu adc/libs/converter-openapi/, các fixture basic-1..7 và extension-1..12 của nó, cùng basic.spec.ts và extension.spec.ts; được xem là hoàn thành khi có chuyển đổi YAML/JSON của OpenAPI 3.x, độ bao phủ tương đương, validation thành công và tài liệu trong docs/.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
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/`.
- Ngôn ngữ chính
- Go
- Star
- 1
- Fork
- 0
- Merge trung bình
- 1 giờ 3 phút
- Pull request đã merge (30 ngày)
- 1
Chuẩn bị môi trường
- Không có Dockerfile hay tệp Docker Compose
- Có mẫu pull request
- Không có hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của api7/a7
-
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 25/100
-
config validate: detect bare/null unsupported sections (true key-presence)Có thể làm lại được @shreemaan-abhishek đã nhận 147 ngày trước và không có pull request nào đang mở. Đang mở
Issue tương tự
-
raised-by:verifier
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
medici-finance/assay#2718 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
connector good first issue help wanted
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
soma-intelligence/open-health-sync#60 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
automation models
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
microsoft/TypeScript#64758 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 62/100
SocialGouv/iterion#2369 ·
Maintainer thường phản hồi trong vòng 1 ngày