Migrate API routes to PHP attributes (#[ApiRoute]) and add OpenAPI support #3622
Description
Context:
The app currently uses two separate mechanisms to define the API: a flat route array in routes.phpand controller methods in Controller This split means every route must be declared in two places, making refactoring error-prone and the API hard to document.
Since News targets Nextcloud 32 (min-version="32"), all of the following are fully available.
Tasks
Replace routes.php entries with #[ApiRoute] attributes (available since NC 27)
Each route declaration in routes.php should be moved onto the corresponding controller method using OCP\AppFramework\Http\Attribute\ApiRoute. Once all routes are covered, the routes array in routes.php can be emptied or removed.
Remove the wildcard CORS preflight route once #[ApiRoute] is adopted throughout, as Nextcloud handles OPTIONS automatically per route.
Add #[OpenAPI] attributes to API controllers (available since NC 28) to control scope inclusion in the generated spec.
Add typed DataResponse<> return types to API controller methods so that occ openapi:generate can produce a usable OpenAPI 3.0 spec. Bare array and untyped JSONResponse returns are not picked up by the generator. The V2 API controllers (FolderApiV2Controller, etc.) are a good starting point.
Run occ openapi:generate and commit the resulting spec.
References
- PR chore: migrate some routes to the new format #2873
- Nextcloud developer docs — Routing https://docs.nextcloud.com/server/32/developer_manual/basics/routing.html
- OCP\AppFramework\Http\Attribute\ApiRoute
- OCP\AppFramework\Http\Attribute\OpenAPI