(MINOR): OpenAPI contract generation for IPatchObject<T>

[PaulTrampert]

Implements the proposal in docs/proposals/openapi-contract-generation.md (also added on this branch, along with the Swagger UI findings).

The problem

A route taking [FromBody] IPatchObject<PersonWriteModel> is documented from the interface, which has no properties. The sample app emitted:

"PersonWriteModelIPatchObject": { "type": "object", "additionalProperties": false }

That's not just uninformative — additionalProperties: false with no properties describes a body that permits nothing, so a strict validator, contract test, or generated client rejects every legal PATCH. In Swagger UI the model renders as an empty box and "Try it out" prefills {}.

The approach

The patch schema is derived from the source model's own schema — clear required, drop properties the patch object can't set, add a description — rather than built by describing the Optional-valued class PatchClassBuilder emits.

Describing the generated class would mean re-solving four things the generator already gets right for T: Optional<T> documents as {hasValue, value}; the schema id becomes the random PersonWriteModel_Optionals_xj1k2h3g, which changes every run; [StringLength] has been rewritten to [OptionalValidation(typeof(StringLengthAttribute))], which no generator recognizes, so constraints are lost; and [JsonConverter] has become [OptionalConverter].

Deriving from T inherits validation, converters, naming policy, and any MapType/filter already applied to the write model — and makes it impossible for the PUT and PATCH contracts to describe different shapes.

What's here

Core (PTrampert.SimplePatch), net8.0 — no new dependencies; its dependency list is unchanged by this PR.

• PatchClassBuilder's cache is now static, with a PatchClassBuilder.Shared instance. Previously PatchJsonConverterFactory had its own private builder; a second builder compiled a second dynamic assembly for the same source type.
• TypeExtensions is public, with TryGetPatchSourceType, which accepts the open interface as well as a concrete implementation. The two existing helpers stay internal.
• Bug fix: patch class generation failed with error CS1001: Identifier expected for source types in the global namespace — the generated namespace came out as ".Optionals". Minimal-API apps declaring models in Program.cs hit this immediately.

PTrampert.SimplePatch.Schema, net8.0 — the one copy of PatchSchemaTransform plus SimplePatchSchemaOptions. Both integrations reference it, so the transform cannot drift between them. It lives here rather than in core because it takes Microsoft.OpenApi types, and core shouldn't hand that dependency to consumers who never generate OpenAPI. net8.0 so both integrations can consume it.

PTrampert.SimplePatch.Swashbuckle, net8.0 — AddSwaggerGen(o => o.AddSimplePatchSchemas()), an ISchemaFilter.

PTrampert.SimplePatch.OpenApi, net10.0 — AddOpenApi(o => o.AddSimplePatchSchemas()), an IOpenApiSchemaTransformer.

Options: Example, SchemaId (t => t.Name + "Patch" for PersonWriteModelPatch), DescriptionFormat, ClearRequired.

Dependency graph

Read back from the packed nuspecs. Each package's lib/ holds only its own assembly; the siblings are NuGet dependencies, pinned to the same build version.

Package	Dependencies
PTrampert.SimplePatch	Microsoft.CodeAnalysis.CSharp, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, System.CodeDom, System.Text.Json
PTrampert.SimplePatch.Schema	↑ + Microsoft.OpenApi 2.12.0
PTrampert.SimplePatch.Swashbuckle	↑ + Swashbuckle.AspNetCore.SwaggerGen 10.2.3
PTrampert.SimplePatch.OpenApi	↑ + Microsoft.AspNetCore.OpenApi 10.0.12

Result

Verified against the sample app:

"PersonWriteModelIPatchObject": {
  "type": "object",
  "properties": {
    "name":        { "maxLength": 255, "minLength": 3, "type": "string" },
    "dateOfBirth": { "type": "string", "format": "date-time" },
    "email":       { "type": "string", "format": "email", "nullable": true },
    "phoneNumber": { "$ref": "#/components/schemas/PhoneNumber" }
  },
  "additionalProperties": false,
  "description": "Partial update of PersonWriteModel. Omitted properties are left unchanged.",
  "example": { "name": "New Name" }
}

In Swagger UI, name renders without the red * while the PUT body built from the same model still shows name* — so a reader can see at a glance that PATCH takes a subset. PATCH round-trips still work, and validation still rejects {"name":"ab"} with a 400.

Two decisions worth a look

Only PTrampert.SimplePatch.OpenApi is .NET 10 — core, .Schema and .Swashbuckle are all net8.0. The proposal called for net9.0 and net10.0 on that one package. Obtaining the source model's schema from a transformer needs OpenApiSchemaTransformerContext.GetOrCreateSchemaAsync, which .NET 10 added and .NET 9 does not have (verified by compiling against 9); .NET 9's OpenAPI.NET 1.6 object model would also fork the shared transform. .NET 8 and 9 apps still get full support through the Swashbuckle package, so the narrowing only affects apps on the built-in generator below .NET 10.

Microsoft.OpenApi is pinned to 2.12.0 in one place: PTrampert.SimplePatch.Schema. Versions at or below 2.3.0 carry GHSA-v5pm-xwqc-g5wc and raise NU1903. Swashbuckle.AspNetCore.SwaggerGen brings 2.3.0, but the schema package's direct reference outranks it, so the single pin covers both integrations — checked by restoring a scratch project that references only PTrampert.SimplePatch.Swashbuckle from a local feed, which resolves Microsoft.OpenApi/2.12.0 with no advisory. Separately, Microsoft.AspNetCore.OpenApi is on 10.0.12 rather than 10.0.1 because earlier 10.0.x pull Microsoft.OpenApi 2.0.0.

Testing

46 tests pass across the three test projects (28 core, 10 Swashbuckle, 8 OpenApi). The integration tests drive the real DI container and schema generator rather than the filter in isolation, and cover: properties and constraints carried over, required cleared while the source model keeps its own, get-only and [JsonIgnore] properties dropped, [JsonPropertyName] honoured, each option, and that no Optional<T> components leak into the document.

All four packages dotnet pack cleanly, with no NU1903.

Release pipeline

No workflow change needed — verified by running the reusable workflow's own commands locally against this branch. project_name names the solution, not a project (dotnet pack ${{inputs.project_name}}.sln), so packing the solution produces all four packages plus symbols; the test projects are IsPackable=false and the sample is a Web SDK project, so neither ships. dotnet nuget push **/*.nupkg accepts the multi-file expansion and pushes each in turn. Push order is alphabetical, so .OpenApi goes up before the .Schema it depends on — harmless, since nuget.org does not resolve dependencies at push time and all four carry the same version from one run.

Notes for you

• I skipped a sample-app end-to-end test project; the Swashbuckle tests already exercise the same path at the same fidelity through real DI. Say the word if you'd rather have one.
• Unrelated, spotted while editing: README.md and docs/getting-started.md refer to IPatchObjectFor<T> and patch.ApplyTo(person), neither of which exists. Left alone to keep this PR focused.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RtsmxAyPuVHce2nkVDZh2v

[github-actions]

✅ PR Title Formatted Correctly

The title of this PR has been updated to match the correct format. Thank you!