From 494d76d104c7a0855b2b30b66d1218ed024d1bb9 Mon Sep 17 00:00:00 2001 From: test Date: Mon, 25 May 2026 16:52:24 +0800 Subject: [PATCH 1/2] docs(converter-openapi): align README extension table with code Two long-standing inaccuracies in the supported-extensions table: 1. x-adc-labels was documented at Root / Path / Operation levels but the Zod schema in src/schema.ts only defines it at the root document and on each operation object. There is no entry for x-adc-labels on the path-item schema, and src/index.ts only reads oas[ExtKey.LABELS] (root, line 44) and operation[ExtKey.LABELS] (operation, line 95). Path-level x-adc-labels passes loose-object validation but is then silently dropped at conversion. Drop the Path row from the table. 2. x-adc-plugins was documented as causing the service to be split when present at Path or Operation level. The actual splitting condition in src/parser.ts parseSeprateService (lines 60-65) only fires on x-adc-service-defaults, x-adc-upstream-defaults, or a sub-level servers: entry. Plugins are merged into route.plugins directly in src/index.ts (lines 82-85, 102) without invoking parseSeprateService. Test fixtures extension-5.yaml and extension-6.yaml both produce a single service in the output despite carrying plugins at every level. Update the description to match. Fixes #446 --- libs/converter-openapi/README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/libs/converter-openapi/README.md b/libs/converter-openapi/README.md index 27bced12..83965857 100644 --- a/libs/converter-openapi/README.md +++ b/libs/converter-openapi/README.md @@ -35,12 +35,9 @@ A library for implementing the OpenAPI specification and ADC profile conversion. Override the name of the generated route - x-adc-labels + x-adc-labels Root Level - Add labels field to the specified level. It supports string and string array formats. - - - Path Level + Add labels field to the specified level. It supports string and string array formats. Operation Level @@ -48,11 +45,10 @@ A library for implementing the OpenAPI specification and ADC profile conversion. x-adc-plugins Root Level - Add plugins field to the specified level. It is an object that contains one or more plugins. + Add plugins field to the specified level. It is an object that contains one or more plugins. Plugins set at the path or operation level are attached directly to the routes generated from that path or operation; they do not by themselves cause the service to be split. Path Level - Plugin objects at the Path level and Operation level will cause the service to be split, i.e. the sub-level containing the plugin will be included in a new service. Operation Level From d9d806ed62a5c93b46ed924c42d5d8480c175168 Mon Sep 17 00:00:00 2001 From: Traky Deng Date: Mon, 25 May 2026 17:04:42 +0800 Subject: [PATCH 2/2] docs(converter-openapi): clarify x-adc-route-defaults does not split the service MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Third inaccuracy in the same table: x-adc-route-defaults was described as 'This field on sub-levels will cause the service to be split.' The splitting condition in parseSeprateService (src/parser.ts lines 60-65) only checks SERVICE_DEFAULTS, UPSTREAM_DEFAULTS, and sub-level servers: — not ROUTE_DEFAULTS. The field is merged into each route via structuredClone spreads in src/index.ts lines 103-105 (root -> path -> operation order, operation wins). Verified against test/assets/extension-7.yaml: the GET service split in that fixture is caused by an operation-level servers: block, not by x-adc-route-defaults; the PUT operation keeps its merged route-defaults on the main service without splitting. --- libs/converter-openapi/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libs/converter-openapi/README.md b/libs/converter-openapi/README.md index 83965857..48fc23de 100644 --- a/libs/converter-openapi/README.md +++ b/libs/converter-openapi/README.md @@ -112,7 +112,7 @@ servers: x-adc-route-defaults Root Level - It supports setting/overriding parameters in the route at various levels. This field on sub-levels will cause the service to be split. + It supports setting/overriding parameters in the route at various levels. Sub-level values override root-level values (operation > path > root); the merged result is applied to each route. This field does not by itself cause the service to be split. Path Level