Skip to content

refactor: drop Asp.Versioning and merge the OpenAPI documents into one - #396

Merged
hhvrc merged 9 commits into
developfrom
fix/openapi-xml-docs-race
Nov 15, 2026
Merged

hhvrc merged 9 commits into
developfrom
fix/openapi-xml-docs-race

Conversation

@hhvrc

@hhvrc hhvrc commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

What does this change?

Removes Asp.Versioning. Versions are now declared per action method, and the API serves one OpenAPI document instead of one per version. This replaces the earlier fix in this PR for the race in Asp.Versioning's document generation: that code path no longer exists, so the semaphore around /openapi is gone too.

Versioning

  • [ApiVersion(n)] (Common/ApiVersioning) goes on action methods and takes one version. Controllers carry no version.
  • Routes keep the {version:apiVersion} placeholder, which ApiVersionRouteConvention fills in from the action's version. Startup fails if a versioned action's route has no placeholder, or a route has a placeholder but no version.
  • The LCG websocket controllers override the shared WebsocketBaseController.Get so their version can sit on a method.

One OpenAPI document

  • Served at /openapi/openshock.json and shown in Scalar.
  • When a newer version of an operation exists at the same path and method, the older one is left out of the document. It is still served.

XML documentation

  • Comes from the built-in Microsoft.AspNetCore.OpenApi source generator. Our own XML loading and transformers are deleted.
  • Each host (API, LCG, Cron) calls AddOpenApi with the shared ConfigureOpenApi, because the generator only runs in the project that makes that call.
  • More operations now have summaries, and responses show their documented text instead of the status name.
  • Removed empty <returns> and <response> tags that showed up as empty descriptions.

Endpoints

  • All paths are unchanged, except /2/account/username/check and /2/tokens/report. Those only existed under v2 because of class-level versioning and are now v1 only.
  • Clients that read /openapi/1.json or /openapi/2.json need to switch to /openapi/openshock.json.

How was it tested?

  • API integration tests (151) and Common unit tests (147) pass in Release.
  • Compared the runtime route table with the one before this change. The only difference is the two removed v2 routes.
  • Compared the new document with the old v1 and v2 documents, ignoring description text:
    • Every operation and every shared schema is identical (parameters, request bodies, responses, content types, security).
    • What's missing is the 9 v1 operations superseded by v2, the 8 schemas only they used, and the two removed routes.
  • LCG has no tests. I checked its routes by building its MVC endpoints in a scratch app (/1/ws/device, /2/ws/hub, /1, /1/ws/live/{hubId}). No live hub or live-control connection was tested.

Checklist

  • The change is focused on one thing.
  • Tests, formatter and linter pass locally.
  • Documentation is updated where behaviour changed.
  • No secrets, credentials or personal data are included.
  • If this touches device control, limits, sharing, authentication or firmware updates, the description says so and explains how it was tested.

Asp.Versioning.OpenApi configures every document through one shared
factory that keeps state in a field, so two documents requested at the
same time (Scalar loads both) corrupt each other and the broken result
is cached for the process. Serialize the /openapi endpoints.

Also load and merge the XML documentation once per process instead of
per document, log when a documentation file is missing or fails to
load, and split OpenShockXmlComments.cs into one file per class.
@hhvrc hhvrc self-assigned this Nov 14, 2026
@hhvrc
hhvrc requested a review from a team as a code owner November 14, 2026 08:44
@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Too many files!

This PR contains 140 files, which is 40 over the limit of 100.

To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch.

Upgrade to a paid plan to raise the limit.

This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 983b7de4-4455-4eab-8698-85a8a8ff87b2
Commits

Reviewing files that changed from the base of the PR and between aaec8e5 and 77ebf80.

Files selected for processing: 140

  • API.IntegrationTests/Tests/OpenApiDocumentTests.cs
  • API/API.csproj
  • API/Controller/Account/Activate.cs
  • API/Controller/Account/Authenticated/ChangeEmail.cs
  • API/Controller/Account/Authenticated/ChangePassword.cs
  • API/Controller/Account/Authenticated/ChangeUsername.cs
  • API/Controller/Account/Authenticated/Deactivate.cs
  • API/Controller/Account/Authenticated/GetAuditLog.cs
  • API/Controller/Account/Authenticated/GetSelf.cs
  • API/Controller/Account/Authenticated/OAuthConnectionRemove.cs
  • API/Controller/Account/Authenticated/OAuthConnectionsList.cs
  • API/Controller/Account/Authenticated/_ApiController.cs
  • API/Controller/Account/CheckUsername.cs
  • API/Controller/Account/Login.cs
  • API/Controller/Account/LoginV2.cs
  • API/Controller/Account/Logout.cs
  • API/Controller/Account/PasswordResetCheckValid.cs
  • API/Controller/Account/PasswordResetComplete.cs
  • API/Controller/Account/PasswordResetInitiate.cs
  • API/Controller/Account/PasswordResetInitiateV2.cs
  • API/Controller/Account/ResendActivation.cs
  • API/Controller/Account/Signup.cs
  • API/Controller/Account/SignupV2.cs
  • API/Controller/Account/VerifyEmail.cs
  • API/Controller/Account/_ApiController.cs
  • API/Controller/Admin/AutomationTokenCreate.cs
  • API/Controller/Admin/AutomationTokenDelete.cs
  • API/Controller/Admin/AutomationTokenList.cs
  • API/Controller/Admin/AutomationTokenPatch.cs
  • API/Controller/Admin/AutomationTokenRotate.cs
  • API/Controller/Admin/Configuration.cs
  • API/Controller/Admin/DeactivateUser.cs
  • API/Controller/Admin/DeleteApiToken.cs
  • API/Controller/Admin/DeleteUser.cs
  • API/Controller/Admin/EmailOutboxBulk.cs
  • API/Controller/Admin/EmailOutboxCancel.cs
  • API/Controller/Admin/EmailOutboxDelete.cs
  • API/Controller/Admin/EmailOutboxList.cs
  • API/Controller/Admin/EmailOutboxRequeue.cs
  • API/Controller/Admin/EmailOutboxStats.cs
  • API/Controller/Admin/EmailOutboxTestSend.cs
  • API/Controller/Admin/EmailProviderBlacklistAdd.cs
  • API/Controller/Admin/EmailProviderBlacklistList.cs
  • API/Controller/Admin/EmailProviderBlacklistRemove.cs
  • API/Controller/Admin/GetAuditLog.cs
  • API/Controller/Admin/GetOnlineDevices.cs
  • API/Controller/Admin/GetOnlineGateways.cs
  • API/Controller/Admin/GetUser.cs
  • API/Controller/Admin/GetUsers.cs
  • API/Controller/Admin/PatchUser.cs
  • API/Controller/Admin/ReactivateUser.cs
  • API/Controller/Admin/SetUserEmail.cs
  • API/Controller/Admin/SetUserName.cs
  • API/Controller/Admin/SetUserPassword.cs
  • API/Controller/Admin/UserNameBlacklistAdd.cs
  • API/Controller/Admin/UserNameBlacklistList.cs
  • API/Controller/Admin/UserNameBlacklistRemove.cs
  • API/Controller/Admin/WebhookAdd.cs
  • API/Controller/Admin/WebhookList.cs
  • API/Controller/Admin/WebhookRemove.cs
  • API/Controller/Device/AssignLCG.cs
  • API/Controller/Device/AssignLCGV2.cs
  • API/Controller/Device/GetSelf.cs
  • API/Controller/Device/Pair.cs
  • API/Controller/Device/_ApiController.cs
  • API/Controller/Devices/DeviceOtaController.cs
  • API/Controller/Devices/DevicesController.cs
  • API/Controller/Devices/GetShockers.cs
  • API/Controller/Devices/_ApiController.cs
  • API/Controller/Integrations/GetControlStatChanges.cs
  • API/Controller/OAuth/Authorize.cs
  • API/Controller/OAuth/HandOff.cs
  • API/Controller/OAuth/SignupFinalize.cs
  • API/Controller/OAuth/SignupGetData.cs
  • API/Controller/OAuth/_ApiController.cs
  • API/Controller/Public/GetStats.cs
  • API/Controller/Public/PublicShareController.cs
  • API/Controller/Sessions/DeleteSessions.cs
  • API/Controller/Sessions/ListSessions.cs
  • API/Controller/Sessions/SessionSelf.cs
  • API/Controller/Sessions/_ApiController.cs
  • API/Controller/Shares/DeleteShareCode.cs
  • API/Controller/Shares/LinkShareCode.cs
  • API/Controller/Shares/Links/AddShocker.cs
  • API/Controller/Shares/Links/CreatePublicShare.cs
  • API/Controller/Shares/Links/DeletePublicShare.cs
  • API/Controller/Shares/Links/EditShocker.cs
  • API/Controller/Shares/Links/List.cs
  • API/Controller/Shares/Links/PauseShocker.cs
  • API/Controller/Shares/Links/RemoveShocker.cs
  • API/Controller/Shares/UserShares/CreateShareInvite.cs
  • API/Controller/Shares/UserShares/GetShares.cs
  • API/Controller/Shares/UserShares/Invites.cs
  • API/Controller/Shares/UserShares/PauseShockerShares.cs
  • API/Controller/Shares/UserShares/RemoveShockerShares.cs
  • API/Controller/Shares/UserShares/UpdateShockerShares.cs
  • API/Controller/Shares/UserShares/_ApiController.cs
  • API/Controller/Shares/_ApiController.cs
  • API/Controller/Shockers/EditShocker.cs
  • API/Controller/Shockers/GetShockerById.cs
  • API/Controller/Shockers/GetShockerLogs.cs
  • API/Controller/Shockers/ListSharedShockers.cs
  • API/Controller/Shockers/ListShockers.cs
  • API/Controller/Shockers/PauseShocker.cs
  • API/Controller/Shockers/RegisterShocker.cs
  • API/Controller/Shockers/RemoveShocker.cs
  • API/Controller/Shockers/SendControl.cs
  • API/Controller/Shockers/ShockerShares.cs
  • API/Controller/Shockers/_ApiController.cs
  • API/Controller/Tokens/DeleteToken.cs
  • API/Controller/Tokens/GetTokenSelf.cs
  • API/Controller/Tokens/ReportTokens.cs
  • API/Controller/Tokens/Tokens.cs
  • API/Controller/Tokens/_ApiController.cs
  • API/Controller/Users/GetSelf.cs
  • API/Controller/Users/GetSelfControlStats.cs
  • API/Controller/Users/LookupByName.cs
  • API/Controller/Version/_ApiController.cs
  • API/Program.cs
  • Common/ApiVersioning/ApiVersionAttribute.cs
  • Common/ApiVersioning/ApiVersionRouteConvention.cs
  • Common/Common.csproj
  • Common/OpenApi/ControllerTagDescriptionTransformer.cs
  • Common/OpenApi/DocumentedResponsesTransformer.cs
  • Common/OpenApi/OpenShockOperationTransformer.cs
  • Common/OpenApi/OpenShockXmlComments.cs
  • Common/OpenApi/SupersededVersionApiDescriptionProvider.cs
  • Common/OpenShockMiddlewareHelper.cs
  • Common/OpenShockServiceHelper.cs
  • Common/Utils/Pagination/PagedResult.cs
  • Cron/Cron.csproj
  • Cron/Program.cs
  • Directory.Build.props
  • Directory.Packages.props
  • LiveControlGateway/Controllers/HubV1Controller.cs
  • LiveControlGateway/Controllers/HubV2Controller.cs
  • LiveControlGateway/Controllers/InstanceDetailsController.cs
  • LiveControlGateway/Controllers/LiveControlController.cs
  • LiveControlGateway/LiveControlGateway.csproj
  • LiveControlGateway/Program.cs

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@hhvrc hhvrc changed the title fix: serialize OpenAPI document generation and load XML docs once fix: OpenAPI document generation Nov 14, 2026
…ingle OpenAPI document

- Add a homegrown [ApiVersion(n)] for action methods. Routes mark the version with the
  {version:apiVersion} placeholder, and an application model convention fills it in. Startup
  fails if a versioned action's route has no placeholder, or a placeholder has no version.
- Serve one OpenAPI document (/openapi/openshock.json) instead of one per version. A
  versioned operation is hidden when a newer version exists at the same path and method.
- Use the built-in Microsoft.AspNetCore.OpenApi XML comment source generator instead of
  our own XML parsing. Each host calls AddOpenApi with the shared ConfigureOpenApi, since
  the generator only runs where that call is made.
- LCG websocket controllers override the shared Get so the version sits on a method.
- Remove the Asp.Versioning packages and the empty <returns>/<response> doc tags.

Endpoint paths are unchanged, except /2/account/username/check and /2/tokens/report, which
were only exposed under v2 as a side effect of class-level versioning and are now v1 only.
@hhvrc hhvrc changed the title fix: OpenAPI document generation refactor: drop Asp.Versioning and merge the OpenAPI documents into one Nov 15, 2026
HubV1Controller and HubV2Controller have no action of their own, only the Get
inherited from WebsocketBaseController. [ApiVersion] may now go on a controller,
where it applies to all its actions (a method attribute still takes precedence),
so the hubs no longer need a Get override just to carry the version.
Same as the hub controllers: its only action is the inherited Get, so the
version goes on the class and the override is gone. Nothing overrides Get
anymore, so WebsocketBaseController.Get is no longer virtual.
- Version develop's new endpoints with method-level [ApiVersion(1)] and
  convert its remaining Asp.Versioning usages.
- Apply develop's OpenAPI changes (3.2, NullableReferenceTransformer
  removed, default document route) to the single-document setup.
- Keep the NU1608 exemption: develop's Npgsql rc.3 and
  Z.EntityFramework.Plus 10.x pins still trip it against EF Core 11.0.0.
Classes: ApiController, Tags, Route, ApiVersion, Authorize, TokenPermission.
Actions: Tags, NonAction, Obsolete, Http*/Route, ApiVersion, AllowAnonymous/
Authorize, TokenPermission, EnableRateLimiting, ResponseCache,
EndpointName/ApiExplorerSettings, Consumes, Produces/ProducesResponseType.

ApiVersion sits next to the route whose {version:apiVersion} it fills.
Attributes of the same kind keep their relative order.
GET /1/account adds [Authorize(UserSessionCookie,ApiToken)] on top of its
controller's [Authorize(UserSessionCookie)], which made the operation
transformer throw and every OpenAPI document request return 500. ASP.NET
combines stacked [Authorize] attributes into one policy accepting the union
of their schemes, so document exactly that.
There is a single document now, so the {documentName} segment only repeated
the host name. MapOpenApi serves the default document ("v1") on a route
without that segment, so the document is registered under that name.
@hhvrc
hhvrc merged commit 2caee6f into develop Nov 15, 2026
25 checks passed
@hhvrc
hhvrc deleted the fix/openapi-xml-docs-race branch November 15, 2026 13:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant