Change Details

The Wikimedia OpenAPI linter requires a root-level `externalDocs` object in every OAD (`wikimedia-require-external-docs` rule, severity: error). The framework never generates this field and provides no way to set it. ##Context `ModuleSpecHandler::run()` builds the top-level document with only five keys: `openapi`, `info`, `servers`, `paths`, `components`. There is no `externalDocs` and no way to supply one from a module definition file: $spec = [ 'openapi' => '3.0.0', 'info' => ..., 'servers' => ..., 'paths' => ..., 'components' => ..., // ← no 'externalDocs' ]; Note: `externalDocs` at the *operation* level is already supported (it is in `$oasKeys` in `SpecBasedModule::makeRouteInfo()`). Only the root-level field is missing. **4 errors — one per REST module.** ##Conditions of acceptance - [ ] Support an `externalDocs` key in the module definition `.json` file, readable by `SpecBasedModule` or `ModuleSpecHandler`. - [ ] When present, include it at the root of the document generated by `ModuleSpecHandler::run()`. - [ ] Add a unit test verifying the field is passed through correctly. ##Related tasks - T425942 (spike that identified this gap)

The Wikimedia OpenAPI linter requires a root-level `externalDocs` object in every OAD (`wikimedia-require-external-docs` rule, severity: error). The framework never generates this field and provides no way to set it. ##Context `ModuleSpecHandler::run()` builds the top-level document with only five keys: `openapi`, `info`, `servers`, `paths`, `components`. There is no `externalDocs` and no way to supply one from a module definition file: $spec = [ 'openapi' => '3.0.0', 'info' => ..., 'servers' => ..., 'paths' => ..., 'components' => ..., // ← no 'externalDocs' ]; Note: `externalDocs` at the *operation* level is already supported (it is in `$oasKeys` in `SpecBasedModule::makeRouteInfo()`). Only the root-level field is missing. **4 errors — one per REST module.** ##Conditions of acceptance - [ ] Support an `externalDocs` key in the module definition `.json` file, readable by `SpecBasedModule` or `ModuleSpecHandler`. This key must support an object structure as defined in the [[ https://spec.openapis.org/oas/v3.0.0.html#external-documentation-object | OpenAPI specification ]]. - [ ] When present, include it at the root of the document generated by `ModuleSpecHandler::run()`. - [ ] Add a unit test verifying the field is passed through correctly. - [] Add the `externalDocs` object to the MediaWiki REST API OAD with the following values: - `description`: API documentation - `url`: https://www.mediawiki.org/wiki/API:REST_API ##Related tasks - T425942 (spike that identified this gap)

The Wikimedia OpenAPI linter requires a root-level `externalDocs` object in every OAD (`wikimedia-require-external-docs` rule, severity: error). The framework never generates this field and provides no way to set it. ##Context `ModuleSpecHandler::run()` builds the top-level document with only five keys: `openapi`, `info`, `servers`, `paths`, `components`. There is no `externalDocs` and no way to supply one from a module definition file: $spec = [ 'openapi' => '3.0.0', 'info' => ..., 'servers' => ..., 'paths' => ..., 'components' => ..., // ← no 'externalDocs' ]; Note: `externalDocs` at the *operation* level is already supported (it is in `$oasKeys` in `SpecBasedModule::makeRouteInfo()`). Only the root-level field is missing. **4 errors — one per REST module.** ##Conditions of acceptance - [ ] Support an `externalDocs` key in the module definition `.json` file, readable by `SpecBasedModule` or `ModuleSpecHandler`. This key must support an object structure as defined in the [[ https://spec.openapis.org/oas/v3.0.0.html#external-documentation-object | OpenAPI specification ]]. - [ ] When present, include it at the root of the document generated by `ModuleSpecHandler::run()`. - [ ] Add a unit test verifying the field is passed through correctly. - [] Add the `externalDocs` object to the MediaWiki REST API OAD with the following values: - `description`: API documentation - `url`: https://www.mediawiki.org/wiki/API:REST_API ##Related tasks - T425942 (spike that identified this gap)