CoreEx.AspNetCore.NSwag 4.0.0-preview-1

CoreEx.AspNetCore.NSwag

Provides the NSwag IOperationProcessor integration that reads CoreEx MVC attributes ([Paging], [Query], [Accepts], [IdempotencyKey], [ProducesNotFoundProblem]) and injects the corresponding parameters, request bodies, and response entries into the generated OpenAPI specification.

Overview

CoreEx.AspNetCore.NSwag bridges CoreEx's declarative MVC attributes with NSwag's OpenAPI document generation pipeline. Without this package, NSwag cannot infer paging query-string parameters, idempotency-key request headers, or standard ProblemDetails error responses from CoreEx's attribute-based conventions.

NSwagOpenApiOperationProcessor is registered as a NSwag IOperationProcessor and runs once per operation during document generation. It reads endpoint metadata for each of the CoreEx MVC attributes and adds the corresponding OpenAPI artifacts — parameters, request-body content types, response entries — to the generated OpenApiOperation. The processor is controlled by OpenApiOptions (from CoreEx.AspNetCore), which exposes flags and display-text properties for every injected element.

CoreExNSwagExtensions.AddCoreExConfiguration() (on OpenApiDocumentGeneratorSettings) is the single registration call that wires both the operation processor and the CoreEx-aligned System.Text.Json schema settings.

Key capabilities

• 📋 Paging parameters: Reads [PagingAttribute] and adds $skip, $take, and optionally $count / $page query-string parameters with descriptions controlled by OpenApiOptions.PagingSkipText, PagingTakeText, etc.
• 🔍 Query parameters: Reads [QueryAttribute] and adds $filter and/or $orderby query-string parameters when SupportsFilter / SupportsOrderBy are set.
• 📦 Request body content types: Reads [AcceptsAttribute] and populates the operation RequestBody with the declared content type(s) and NSwag-inferred JSON schema for the body type.
• 🔑 Idempotency-key header: Reads [IdempotencyKeyAttribute] and adds an x-idempotency-key header parameter to the operation.
• 🚫 Not-found response: Reads [ProducesNotFoundProblemAttribute] and adds a 404 application/problem+json response entry.
• ⚠️ ProblemDetails responses: Optionally injects application/problem+json response entries for the HTTP status codes configured via OpenApiOptions.IncludeProblemDetailsHttpStatusCodes / OpenApiOptions.IncludeValidationProblemDetailsHttpStatusCodes and their corresponding status-code lists; 500 is only included when it is present in the configured list, not by default via a separate IncludeStandardProblemDetailsResponses option.
• 📡 Fields query string: When OpenApiOptions.IncludeFieldsRequestHeaders is set, adds the $fields query-string parameter for response field projection.
• 💬 Message response headers: When OpenApiOptions.IncludeMessagesResponseHeaders is set, documents x-messages-warning and x-messages-info response headers.
• ⚙️ STJ schema settings: ConfigureSchemaSettings() aligns NSwag's JSON schema generation with JsonDefaults.SerializerOptions (camelCase, enum-as-string, WhenWritingDefault) so the generated schema matches the actual serialized output.

Key types

Related Namespaces

• CoreEx.AspNetCore - Defines OpenApiOptions (processor configuration), and the MVC attributes ([PagingAttribute], [QueryAttribute], [AcceptsAttribute], [IdempotencyKeyAttribute], [ProducesNotFoundProblemAttribute]) read by this processor.
• CoreEx.Http - HttpNames provides the configurable query-string and header name constants used when creating OpenAPI parameter names.
• CoreEx.Json - JsonDefaults.SerializerOptions is the options instance applied to NSwag schema settings by ConfigureSchemaSettings().

Additional Resources

• NSwag GitHub - The NSwag library this package extends.

AI Usage Guide

An AGENTS.md file is included with this package. AI coding assistants (GitHub Copilot, Claude, Cursor, etc.) that support workspace-injected package documentation will automatically surface concise usage guidance, code examples, and Do Not rules for this package without requiring a local CoreEx checkout.