Repository navigation
refactor: drop Asp.Versioning and merge the OpenAPI documents into one - #396
Merged
Merged
Conversation
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.
|
Important Review skippedToo 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.
|
…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.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
/openapiis gone too.Versioning
[ApiVersion(n)](Common/ApiVersioning) goes on action methods and takes one version. Controllers carry no version.{version:apiVersion}placeholder, whichApiVersionRouteConventionfills 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.WebsocketBaseController.Getso their version can sit on a method.One OpenAPI document
/openapi/openshock.jsonand shown in Scalar.XML documentation
AddOpenApiwith the sharedConfigureOpenApi, because the generator only runs in the project that makes that call.<returns>and<response>tags that showed up as empty descriptions.Endpoints
/2/account/username/checkand/2/tokens/report. Those only existed under v2 because of class-level versioning and are now v1 only./openapi/1.jsonor/openapi/2.jsonneed to switch to/openapi/openshock.json.How was it tested?
/1/ws/device,/2/ws/hub,/1,/1/ws/live/{hubId}). No live hub or live-control connection was tested.Checklist