docs: modularize the 3.19 Admin API OpenAPI specification

.gitattributes

@@ -1 +1,2 @@
 t/**/*.t linguist-vendored
+docs/en/latest/admin-api.json linguist-generated=true

.github/workflows/doc-lint.yml

@@ -5,18 +5,37 @@ on:
     paths:
       - "docs/**"
       - "**/*.md"
+      - "Makefile"
+      - "utils/bundle-admin-api-spec.sh"
       - ".github/workflows/doc-lint.yml"
   pull_request:
     branches: [master, "release/**"]
     paths:
       - "docs/**"
       - "**/*.md"
+      - "Makefile"
+      - "utils/bundle-admin-api-spec.sh"
       - ".github/workflows/doc-lint.yml"
 
 permissions:
   contents: read
 
 jobs:
+  admin-api-openapi:
+    name: Admin API OpenAPI
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Use Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: "22.12.0"
+      - name: Bundle Admin API OpenAPI document
+        run: make bundle-admin-api-spec
+      - name: Check generated bundle
+        run: git diff --exit-code -- docs/en/latest/admin-api.json
+
   markdownlint:
     name: 🍇 Markdown
     runs-on: ubuntu-24.04

Makefile

@@ -559,3 +559,8 @@ merge-dev-tags:
 		$(IMAGE_NAME):dev-arm64
 	$(ENV_DOCKER) manifest push $(IMAGE_NAME):dev
 	@$(call func_echo_success_status, "$@ -> [ Done ]")
+
+### bundle-admin-api-spec : Generate the bundled Admin API OpenAPI document
+.PHONY: bundle-admin-api-spec
+bundle-admin-api-spec:
+	./utils/bundle-admin-api-spec.sh

docs/openapi/admin-api/README.md

@@ -0,0 +1,51 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# Admin API OpenAPI Source
+
+This directory contains the modular source for the Admin API OpenAPI
+document.
+
+- `openapi.yaml` defines document metadata and references each path and
+  component module.
+- `paths/` contains one OpenAPI Path Item per file.
+- `components/` contains one reusable OpenAPI component per file, grouped
+  by component type.
+
+Edit these source files rather than
+`docs/en/latest/admin-api.json`. Generate the self-contained document after
+making a change:
+
+```shell
+make bundle-admin-api-spec
+```
+
+The command uses a pinned Redocly CLI version, resolves all external
+references, and writes deterministic, formatted JSON to
+`docs/en/latest/admin-api.json`. CI runs the same command and fails when the
+committed bundle is stale.
+
+Generating the bundle requires Node.js 22.12.0 or later and npm. The script
+invokes `@redocly/cli@2.72.1` explicitly so local and CI generation use the
+same bundler version.
+
+References inside a module are relative to that module. For example, a path
+module can reference a schema with
+`../components/schemas/Route.yaml`, while one schema can reference another
+schema in the same directory with `./ResourceId.yaml`.

docs/openapi/admin-api/components/parameters/FilterExpr.yaml

@@ -0,0 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: filter
+in: query
+required: false
+schema:
+  type: string
+description: Filter expression. Supports `service_id` and `upstream_id`. URL-encoded query string, e.g. `service_id%3D1`.

docs/openapi/admin-api/components/parameters/Force.yaml

@@ -0,0 +1,25 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: force
+in: query
+required: false
+schema:
+  type: string
+  enum:
+    - "true"
+description: When `true`, skip dependency checks before deletion.
+example: "true"

docs/openapi/admin-api/components/parameters/IdInPath.yaml

@@ -0,0 +1,23 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: id
+in: path
+required: true
+schema:
+  $ref: ../schemas/ResourceId.yaml
+description: Resource identifier.
+example: r1

docs/openapi/admin-api/components/parameters/LabelFilter.yaml

@@ -0,0 +1,23 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: label
+in: query
+required: false
+schema:
+  type: string
+description: Filter list to resources with the given label key.
+example: env

docs/openapi/admin-api/components/parameters/NameFilter.yaml

@@ -0,0 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: name
+in: query
+required: false
+schema:
+  type: string
+description: Filter list by `name` (regex match).

docs/openapi/admin-api/components/parameters/Page.yaml

@@ -0,0 +1,25 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: page
+in: query
+required: false
+schema:
+  type: integer
+  minimum: 1
+  default: 1
+description: Page number (1-based).
+example: 1

docs/openapi/admin-api/components/parameters/PageSize.yaml

@@ -0,0 +1,25 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: page_size
+in: query
+required: false
+schema:
+  type: integer
+  minimum: 10
+  maximum: 500
+description: Items per page (10–500). When omitted, no pagination is applied and the full list is returned.
+example: 20

docs/openapi/admin-api/components/parameters/PluginListAll.yaml

@@ -0,0 +1,25 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: all
+in: query
+required: true
+schema:
+  type: string
+  enum:
+    - "true"
+description: Deprecated. When `true`, return the full plugin catalog.
+deprecated: true

docs/openapi/admin-api/components/parameters/PluginNameInPath.yaml

@@ -0,0 +1,24 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: plugin_name
+in: path
+required: true
+schema:
+  type: string
+  minLength: 1
+description: Plugin name.
+example: limit-count

docs/openapi/admin-api/components/parameters/ResourceKindInPath.yaml

@@ -0,0 +1,35 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: resource
+in: path
+required: true
+schema:
+  type: string
+  enum:
+    - routes
+    - services
+    - upstreams
+    - consumers
+    - ssls
+    - plugin_configs
+    - global_rules
+    - stream_routes
+    - protos
+    - consumer_groups
+    - credentials
+description: Resource kind.
+example: routes

docs/openapi/admin-api/components/parameters/SecretType.yaml

@@ -0,0 +1,27 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: secret_type
+in: path
+required: true
+schema:
+  type: string
+  enum:
+    - vault
+    - aws
+    - gcp
+description: Secret manager backend.
+example: vault