Skip to content

Latest commit

 

History

History

CoreEx.AspNetCore.NSwag

README.md

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 query-string parameters with descriptions controlled by OpenApiOptions.PagingSkipText, PagingTakeText, etc.
  • 🔍 Query parameters: Reads [QueryAttribute] and adds $filter, $orderby and/or $search query-string parameters when SupportsFilter / SupportsOrderBy / SupportsSearch 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 Idempotency-Key header parameter to the operation. Send one quoted RFC 9651 Structured Field string, for example Idempotency-Key: "order-12345678"; the documented 8-128 character length applies to the decoded logical key, not its quotes or escapes. Parameters are not accepted.

The server's default relaxed mode also accepts the documented legacy bare-key syntax for compatibility; standards-only deployments enable StrictHeaderValidation on the HTTP idempotency provider. OpenAPI describes the standard quoted wire format and does not imply that authorization may be skipped on replay.

  • ✅ Non-nullable properties: Walks the request/response types of each operation and marks any property decorated with CoreEx.Entities.NonNullableAttribute as nullable: false in the schema, regardless of whether it is declared nullable in code (e.g. string?, int?).
  • 📝 Optional patch properties: Unwraps Optional<T> to its inner schema, keeps the property out of the required list, and derives nullability from the inner type.
  • 🚫 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

Type Description
NSwagOpenApiOperationProcessor NSwag IOperationProcessor that reads CoreEx endpoint metadata and injects paging, query, accepts, idempotency-key, not-found, ProblemDetails, fields, and message-header artifacts into each OpenApiOperation.
CoreExNSwagExtensions OpenApiDocumentGeneratorSettings extension methods: AddCoreExConfiguration() (registers processor + schema settings), AddOpenApiDocumentExtensions(configure?), ConfigureSchemaSettings(jsonSerializerOptions?).

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

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.