Resources added by modules are discovered automatically, with their endpoints, allowed operations and entity fields. What the browser cannot infer is the meaning of a module's custom JSON-LD keys and query parameters. An adapter can supply those by implementing one method.
The apiBrowserSchema() hook
Add a public apiBrowserSchema() method to the adapter class and return an array with any of three keys:
public function apiBrowserSchema(): array
{
return [
'jsonLdKeys' => [
'o-module-blog:status' => [
'type' => 'string',
'description' => 'Editorial status: draft, scheduled or published.',
],
],
'queryParams' => [
['name' => 'status', 'type' => 'string', 'description' => 'Filter by editorial status.'],
['name' => 'category_id', 'type' => 'integer', 'description' => 'Filter by category.'],
],
'bodyParams' => [
['name' => 'include_files', 'type' => 'boolean', 'default' => true, 'description' => 'Include uploaded files.'],
],
];
}
| Key | Shape | Used for |
|---|---|---|
jsonLdKeys |
map of key name to type and description |
Documents keys in the resource's responses. Merged with the browser's own catalog. |
queryParams |
list of name, type, description |
Documents search filters. Merged with the common parameters (page, per_page, sort_by and so on). |
bodyParams |
list of name, type, default, description |
Documents the request body for create and update. Replaces any inferred body documentation. |
Types are plain strings such as string, integer, boolean, array or object; they are mapped to OpenAPI types in the export.
Notes
- The method is called on a fresh instance of the adapter with no constructor arguments, so it must not rely on injected services.
- If the method throws, the browser records a note on the resource and continues with the inferred schema.
- The hook affects documentation only. It does not change how the adapter validates or handles requests.
The Blog and Backup modules from RefBytes implement this hook and are a good reference.