api7 / api7/a7

Support OpenAPI specification as a declarative config source

Open
#60 1 comment 1 reaction 0 assignees View on GitHub

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

  1. Schema library — Go ecosystem has `getkin/kin-openapi` (most common) and `pb33f/libopenapi`. Pick one that handles 3.0 + 3.1.
  2. Extension namespace — adc uses `x-adc-`. We could keep that, switch to `x-a7-`, or accept both for compatibility with adc-generated specs.
  3. Round-trip — is the inverse (`a7 config → OpenAPI`) in scope? adc does not do this; would suggest deferring.
  4. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.