2404 stack 1 openapi generator and lint - #2443
Open
correct-horse-battery-bench wants to merge 3 commits into
Open
2404 stack 1 openapi generator and lint#2443correct-horse-battery-bench wants to merge 3 commits into
correct-horse-battery-bench wants to merge 3 commits into
Conversation
The spec was assembled inline in the openapi.json route closure, with the schema helpers spread over OpenAPISchemaUtils and openAPISchema.routes.php. It moves into a library under src/inc/apiv2/openapi/, with ApiRegistry as the single source of truth for which APIv2 classes exist. The document declares openapi 3.1.0 and describes the surface the API actually has: per model Count, bulk and single response schemas, the getGlobalConfig, getCompletedCount and getCracksPerDay helper paths, and the pagination links the runtime answers with (self, first, last, next, prev), with a single resource document carrying only a self link. It also describes only what the server answers today. A resource id is an integer, because that is what obj2Resource puts in the document; the string form JSON:API asks for is described once the runtime serializes it as one. There is one spec endpoint, GET /api/v2/openapi.json, answering the sanitized document, plus ci/tools/generate-openapi.php, which produces the identical document without a database or a server. Two changes follow from generating it offline: - AgentAPI reads hideIpInfo when it filters instead of in the constructor, because the generator instantiates the API classes purely to introspect them. - GetUserPermissionHelperAPI names the schema prefix of the model API it answers with (GlobalPermissionGroup), not the name of the DBA model.
The lint job was green without checking anything: the spec master serves declares openapi 3.0.1, while the upstream JSON:API ruleset declares formats: [oas3.1], so Spectral skipped every rule. The 3.1.0 output of the generator activates the whole ruleset at once. spectral-hashtopolis.yml extends the upstream ruleset, which stays unmodified so it can be updated from upstream, and records every point where the APIv2 departs from JSON:API, naming the code that decides the behaviour. A rule is re-scoped wherever part of it still holds: - resource-object-property-types and relationship-data-schema keep their type and meta clauses. Their id clause cannot hold while obj2Resource answers the integer primary key of the model. - content-type, the response code rules and the single object rules hold for the resource routes under /api/v2/ui/. The routes under /api/v2/helper/ are RPC style actions that take a flat body and answer a meta document. Three rules are switched off, because the behaviour they describe is absent altogether rather than narrower than upstream assumes: 406-response-code and 415-response-code (no content negotiation middleware exists) and patch-requests-single-object (a collection PATCH carries a list of objects). Each of the three names what has to change for it to come back. Spectral does not inherit the aliases of an extended ruleset, so the aliases the re-scoped rules use are copied into this file.
correct-horse-battery-bench
force-pushed
the
2404-stack-1-openapi-generator-and-lint
branch
from
August 18, 2026 07:44
e1facca to
73ecc7b
Compare
s3inlc
requested changes
Aug 18, 2026
MODEL_API_CLASSES declares list<class-string<AbstractModelAPI>>, while HELPER_API_CLASSES declared the bare list<class-string>, so nothing said the entries are helper APIs. Every class in the list extends AbstractHelperAPI, and the consumers of the constant call the methods that base class declares.
correct-horse-battery-bench
marked this pull request as ready for review
August 18, 2026 14:17
s3inlc
approved these changes
Aug 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refactor openapi spec generator to be in its own module, output openapi 3.1.0 version output and make sure it can generate the spec without needing a live db or application just from the registered model classes.