kayx23 opened a new issue, #14145: URL: https://github.com/apache/apisix/issues/14145
## Current State The APISIX 3.19 Admin API OpenAPI document is committed at `docs/en/latest/admin-api.json` as one minified line. This creates several maintenance problems: - GitHub reports any change as one deleted line and one added line, even when many unrelated schemas change. - Reviewers cannot use the normal line-by-line review interface to isolate semantic edits. - Concurrent changes are likely to conflict on the same physical line. - The repository does not provide a documented command that reproduces the committed document from smaller source files. - Repeated and derived schemas are difficult to update consistently. - Validation can confirm that the final document parses, but it does not establish that a committed bundle is current with an authoritative source tree. For comparison, `docs/en/latest/control-api.json` is already stored as readable, multi-line JSON. The immediate schema corrections in #14137 should be reviewed and merged first. This issue is follow-up maintenance work and should not block, precede, or expand that correction PR. ## Desired State Maintain the Admin API OpenAPI definition in a reviewable source form and produce the published `docs/en/latest/admin-api.json` through one deterministic command. A preferred implementation would combine modularization and formatting in one migration after #14137 merges: ```text docs/openapi/admin-api/ ├── openapi.yaml ├── paths/ ├── components/ │ ├── schemas/ │ ├── parameters/ │ ├── responses/ │ └── examples/ └── README.md docs/en/latest/admin-api.json # generated, bundled, self-contained output ``` The exact directory names and whether the source modules use YAML or JSON can be decided during implementation. The important properties are: 1. Contributors edit the modular source, not the bundled artifact. 2. A repository-approved, version-pinned tool resolves the modules and produces a self-contained OpenAPI document. 3. The generated JSON is deterministically pretty-printed and ends with a newline. 4. The generated file remains available at its existing path for documentation tooling and raw-file consumers. 5. Contributor documentation explains how to validate and regenerate it. 6. CI regenerates the bundle and fails if the working tree changes. 7. CI lints the source and bundled OpenAPI documents and verifies that all internal references resolve. 8. If the generated bundle is committed, it is identified as generated so reviewers can focus on the source diff. ### Migration safety The migration itself should not change the API contract. It should demonstrate semantic equivalence between the document immediately before migration and the newly generated bundle, for example by: - parsing both documents; - normalizing object-key order; - comparing the normalized JSON structures; - validating that the same OpenAPI version, paths, operations, components, examples, and internal references remain present; and - running the existing OpenAPI validation with no new errors or warnings. Running the generator twice should produce byte-identical output. ### CI and contributor workflow A possible workflow is: ```shell make lint-admin-api-spec make bundle-admin-api-spec git diff --exit-code -- docs/en/latest/admin-api.json ``` The concrete command names are only examples. The selected commands should be documented and usable both locally and in CI. A pull request that changes the contract should then show: - focused changes in the relevant source modules; - the corresponding deterministic generated-bundle update; and - validation results for both source and bundle. ### Lower-risk fallback If modularization is considered too large for one migration, a smaller first step could pretty-print `admin-api.json` and add a deterministic formatting check. That would immediately restore line-level review. Modular source files and bundling could follow separately. The combined migration is preferable if it can preserve semantic equivalence and keep the implementation reasonably small, because it avoids establishing another temporary manual-editing convention. ## Acceptance Criteria - [ ] #14137 is merged before implementation begins. - [ ] The authoritative Admin API OpenAPI source is reviewable as normal multi-line files. - [ ] One documented command generates a self-contained `docs/en/latest/admin-api.json`. - [ ] The generated JSON is deterministic and consistently formatted. - [ ] The migration is proven semantically equivalent to the pre-migration document. - [ ] CI validates OpenAPI structure and references. - [ ] CI detects stale generated output. - [ ] Contributor instructions identify which files are edited and which are generated. - [ ] A small schema change produces a focused, understandable pull-request diff. ## Non-Goals - Changing Admin API runtime behavior. - Adding unrelated schema corrections during the migration. - Requiring this maintenance work to land before #14137. - Redesigning the Control API specification in the same change. The same approach can be evaluated separately if useful. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
