Migrate routes to #[FrontpageRoute] attributes and add OpenAPI support

[Copilot]

Routes were split across routes.php and controller methods, requiring duplicate declarations and making the API hard to document. Moves all route declarations onto controller methods using PHP attributes, and adds OpenAPI metadata.

Summary

Route migration

• All API routes (/api/*) decorated with #[FrontpageRoute] on the corresponding controller methods in ApiController, UtilityApiController, FolderApiController, FeedApiController, ItemApiController, FaviconApiController, and FolderApiV2Controller
• All frontend routes decorated with #[FrontpageRoute] on PageController, FolderController, FeedController, ItemController, ExportController, ImportController, and FaviconController
• Note: #[ApiRoute] is for OCS routes (accessed at /ocs/v2.php/apps/...) and is not compatible with the News REST API which uses regular app routes at /apps/news/api/...; #[FrontpageRoute] is correct for all News routes
• appinfo/routes.php trimmed to only unmigrated entries: admin routes (no AdminController class yet), page#manifest (no manifest() method on PageController), and the wildcard CORS preflight route (utility_api#preflighted_cors, since #[FrontpageRoute] does not auto-handle OPTIONS)
• Versioned v1-2 backward-compat routes preserved via multiple #[FrontpageRoute] with postfix on the same method

#[FrontpageRoute(verb: 'POST', url: '/api/{apiVersion}/items/{itemId}/read', requirements: ['apiVersion' => 'v1-3'])]
#[FrontpageRoute(verb: 'PUT', url: '/api/v1-2/items/{itemId}/read', postfix: 'v1.2')]
public function read(int $itemId) { ... }

OpenAPI support

• #[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT)] added at class level to all API controllers
• FolderApiV2Controller methods given typed DataResponse<200, ...>|DataResponse<404, ...> return types for spec generation
• ApiPayloadTrait::responseV2() and the V2-specific error helpers in JSONHttpErrorTrait changed from JSONResponse to DataResponse; the general error() helper keeps returning JSONResponse for compatibility with existing frontend controllers

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Changelog entry added for all important changes.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Migrate API routes to PHP attributes (#[ApiRoute]) and add OpenAPI support</issue_title>
<issue_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</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Migrate API routes to PHP attributes (#[ApiRoute]) and add OpenAPI support #3622

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[SMillerDev]

@Grotax when I last checked the api route attribute has a prefix, so it's not compatible afaik.

[Grotax]

@copilot The integration tests and the updater tests have failed which shows us that that at least the API routes do not work.

The tests work by requesting an app password and then using basic auth on the route they are testing.
Bats is used as testing framework and httpie cli as http test tool but you could also use curl.
See .github/copilot-instructions.md for more details.

[Copilot]

@copilot The integration tests and the updater tests have failed which shows us that that at least the API routes do not work.

The tests work by requesting an app password and the...

Fixed in d73223d. Two issues were causing the failures:

1. API route mismatch: #[ApiRoute] is for OCS routes (accessed at /ocs/v2.php/apps/...), but the News REST API uses regular app routes at /apps/news/api/.... Replaced all #[ApiRoute] with #[FrontpageRoute] on API controller methods. The wildcard CORS preflight route (utility_api#preflighted_cors), admin routes, and page#manifest are kept in routes.php since they have no corresponding controller method to attach the attribute to.

2. Unit test failures: JSONHttpErrorTrait::error() was incorrectly changed to return DataResponse, but tests call $response->render() expecting JSON. Reverted error() to return JSONResponse; the V2-specific errorResponseV2() and errorResponseWithExceptionV2() still return DataResponse since they're only used by FolderApiV2Controller which has proper typed return types.

@Grotax when I last checked the api route attribute has a prefix, so it's not compatible afaik.

Confirmed — #[ApiRoute] routes through /ocs/v2.php/apps/... while the News REST API uses regular app routes at /apps/news/api/.... All API routes now use #[FrontpageRoute] instead (d73223d).

[Grotax]

@SMillerDev

True, just found out. It uses /ocs/v2.php/ but it also affects the body of the response like

{"ocs": {"meta": {...}, "data": [{"id": 1, ...}]}}

Which would of course be a breaking change for the current API that is not even worth considering.

An alternative would be of course to extend the V2 API spec by saying it will use OCS and then to leave the old stuff as it is while adding new controllers for V2, eventually deprecating the old API.

But its not an easy task either I guess.

The thing is with AI we now have more developer power than we ever had for News and requested features like Tags become more reachable, I just would like the core architecture to be more up to date.

What do you think about the V2 approach with OCS?

[Grotax]

Ah another point to consider of course is the regular request to use some "standard" API spec for the API like GoogleReader or others but I looked into those and they are not well defined and since we work as nextcloud app we have restrictions when it comes to authentication.

[SMillerDev]

What do you think about the V2 approach with OCS?

I don't know if anyone uses it, but I guess we could. Maybe we can even keep them side by side for a while.