feat: DEVPLAN 1.13.10 add OpenAPI document generation via CoreIdent.OpenApi package

Create new CoreIdent.OpenApi project with .NET 10 Microsoft.AspNetCore.OpenApi integration; add service registration and endpoint mapping extensions; configure security schemes, request/response examples, and XML documentation; add OpenAPI validation gate to CI workflow; update Developer_Guide.md and README_Detailed.md with setup instructions and optional Scalar UI integration; complete DEVPLAN 1.13.10 checklist items.

Author: stimpy77

.github/workflows/dotnet.yml

@@ -40,6 +40,9 @@ jobs:
       - name: Test (with coverage)
         run: dotnet test CoreIdent.sln -c Release --no-build --collect:"XPlat Code Coverage" --logger "console;verbosity=minimal"
 
+      - name: OpenAPI Validation Gate
+        run: dotnet test tests/CoreIdent.Integration.Tests/CoreIdent.Integration.Tests.csproj -c Release --no-build --filter "FullyQualifiedName~CoreIdent.Integration.Tests.Infrastructure.OpenApiFixtureTests" --logger "console;verbosity=minimal"
+
       - name: Coverage Gate (CoreIdent.Core >= 90%)
         run: |
           python3 - <<'PY'

CoreIdent.sln

@@ -7,6 +7,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{827E0CD3-B72
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreIdent.Core", "src\CoreIdent.Core\CoreIdent.Core.csproj", "{13763257-46A9-43D3-B447-01E9B886AB99}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreIdent.OpenApi", "src\CoreIdent.OpenApi\CoreIdent.OpenApi.csproj", "{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreIdent.Passkeys", "src\CoreIdent.Passkeys\CoreIdent.Passkeys.csproj", "{7DAD0A0D-9B1B-4C2B-A758-9E5D5C1C4B8A}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreIdent.Passkeys.AspNetIdentity", "src\CoreIdent.Passkeys.AspNetIdentity\CoreIdent.Passkeys.AspNetIdentity.csproj", "{A8E0F5F1-86B0-4E6E-9B8D-0C2C15FA1C9D}"
@@ -59,6 +61,18 @@ Global
 		{13763257-46A9-43D3-B447-01E9B886AB99}.Release|x64.Build.0 = Release|Any CPU
 		{13763257-46A9-43D3-B447-01E9B886AB99}.Release|x86.ActiveCfg = Release|Any CPU
 		{13763257-46A9-43D3-B447-01E9B886AB99}.Release|x86.Build.0 = Release|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Debug|x64.Build.0 = Debug|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Debug|x86.Build.0 = Debug|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Release|x64.ActiveCfg = Release|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Release|x64.Build.0 = Release|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Release|x86.ActiveCfg = Release|Any CPU
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2}.Release|x86.Build.0 = Release|Any CPU
 		{7DAD0A0D-9B1B-4C2B-A758-9E5D5C1C4B8A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{7DAD0A0D-9B1B-4C2B-A758-9E5D5C1C4B8A}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{7DAD0A0D-9B1B-4C2B-A758-9E5D5C1C4B8A}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -247,5 +261,6 @@ Global
 		{CE3F11D3-060F-4F4C-8A40-5A67AFDAD1D0} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
 		{D5A2C0E8-2B2F-4A54-9EA1-6E5D3C59D6E7} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
 		{A90B9D37-39B3-4AE4-8AE1-52E5A02CB200} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
+		{7C1E8B5E-37B3-4E71-9A5F-8E2B8D9AD8B2} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 	EndGlobalSection
 EndGlobal

docs/DEVPLAN.md

@@ -1362,10 +1362,10 @@ This document provides a detailed breakdown of tasks, components, test cases, an
 ---
 
 *   **Component:** OpenAPI Integration Package
-    - [ ] (L1) Create new project `CoreIdent.OpenApi` targeting `net10.0`
-    - [ ] (L1) Add dependency on `Microsoft.AspNetCore.OpenApi` for .NET 10 OpenAPI support
-    - [ ] (L1) Add dependency on `CoreIdent.Core` for access to endpoint models
-    - [ ] (L2) Design OpenAPI configuration options:
+    - [x] (L1) Create new project `CoreIdent.OpenApi` targeting `net10.0`
+    - [x] (L1) Add dependency on `Microsoft.AspNetCore.OpenApi` for .NET 10 OpenAPI support
+    - [x] (L1) Add dependency on `CoreIdent.Core` for access to endpoint models
+    - [x] (L2) Design OpenAPI configuration options:
         ```csharp
         public class CoreIdentOpenApiOptions
         {
@@ -1376,46 +1376,46 @@ This document provides a detailed breakdown of tasks, components, test cases, an
             public bool IncludeSecurityDefinitions { get; set; } = true;
         }
         ```
-    - [ ] (L2) Create extension method `AddCoreIdentOpenApi()` for `IServiceCollection`
-    - [ ] (L2) Create extension method `MapCoreIdentOpenApi()` for `IEndpointRouteBuilder`
-    - [ ] (L2) Configure OpenAPI document to include:
+    - [x] (L2) Create extension method `AddCoreIdentOpenApi()` for `IServiceCollection`
+    - [x] (L2) Create extension method `MapCoreIdentOpenApi()` for `IEndpointRouteBuilder`
+    - [x] (L2) Configure OpenAPI document to include:
         - All OAuth 2.0 and OIDC endpoints (token, authorize, userinfo, etc.)
         - Passwordless endpoints (magic links, OTPs, WebAuthn)
         - Token management endpoints
         - Discovery endpoints (.well-known)
         - JWKS endpoint
         - Passkey endpoints (if enabled)
-    - [ ] (L2) Add proper security schemes:
+    - [x] (L2) Add proper security schemes:
         - `client_secret_basic` for client authentication
         - `client_secret_post` for client authentication
         - `authorization_code` flow with PKCE
         - `refresh_token` flow
         - `Bearer` token authentication
-    - [ ] (L2) Add request/response examples for key endpoints
-    - [ ] (L2) Add descriptions from XML documentation to OpenAPI schemas
+    - [x] (L2) Add request/response examples for key endpoints
+    - [x] (L2) Add descriptions from XML documentation to OpenAPI schemas
 
 *   **Component:** Optional API Reference UI (Scalar)
-    - [ ] (L2) Do not ship a UI in CoreIdent packages (no Swashbuckle / no Swagger UI)
-    - [ ] (L2) Ensure the generated OpenAPI document is compatible with Scalar
-    - [ ] (L2) Document how a host app can add Scalar to serve the OpenAPI JSON (host-managed)
+    - [x] (L2) Do not ship a UI in CoreIdent packages (no Swashbuckle / no Swagger UI)
+    - [x] (L2) Ensure the generated OpenAPI document is compatible with Scalar
+    - [x] (L2) Document how a host app can add Scalar to serve the OpenAPI JSON (host-managed)
 
 *   **Documentation Updates:**
-    - [ ] (L2) Update `Developer_Guide.md` with OpenAPI setup instructions
-    - [ ] (L2) Add OpenAPI configuration examples to README_Detailed.md
-    - [ ] (L2) Document security scheme usage in API documentation
-    - [ ] (L2) Document optional Scalar integration (no UI implementation in CoreIdent)
+    - [x] (L2) Update `Developer_Guide.md` with OpenAPI setup instructions
+    - [x] (L2) Add OpenAPI configuration examples to README_Detailed.md
+    - [x] (L2) Document security scheme usage in API documentation
+    - [x] (L2) Document optional Scalar integration (no UI implementation in CoreIdent)
 
 *   **Test Cases:**
-    - [ ] (L2) OpenAPI document builds without warnings
-    - [ ] (L2) All public endpoints are included in OpenAPI document
-    - [ ] (L2) Security schemes are properly defined and usable
-    - [ ] (L2) Smoke test: `GET /openapi/v1.json` returns 200 with valid OpenAPI document
+    - [x] (L2) OpenAPI document builds without warnings
+    - [x] (L2) All public endpoints are included in OpenAPI document
+    - [x] (L2) Security schemes are properly defined and usable
+    - [x] (L2) Smoke test: `GET /openapi/v1.json` returns 200 with valid OpenAPI document
 
 *   **Quality Gates:**
-    - [ ] (L2) OpenAPI document passes validation (no schema errors)
-    - [ ] (L2) All examples in documentation are valid
-    - [ ] (L2) Security definitions match actual endpoint requirements
-    - [ ] (L2) CI build includes OpenAPI validation step
+    - [x] (L2) OpenAPI document passes validation (no schema errors)
+    - [x] (L2) All examples in documentation are valid
+    - [x] (L2) Security definitions match actual endpoint requirements
+    - [x] (L2) CI build includes OpenAPI validation step
 
 ---
 

docs/Developer_Guide.md

@@ -218,6 +218,55 @@ app.MapCoreIdentEndpoints();
 app.Run();
 ```
 
+## 1.2 OpenAPI documentation (Feature 1.13.10)
+
+CoreIdent supports OpenAPI document generation via the `CoreIdent.OpenApi` package (built on .NET 10's `Microsoft.AspNetCore.OpenApi`).
+
+CoreIdent does **not** ship a built-in UI (no Swashbuckle / Swagger UI). Instead, the host app can optionally add a UI such as Scalar.
+
+### 1.2.1 Add OpenAPI services
+
+Add the package reference:
+
+```xml
+<PackageReference Include="CoreIdent.OpenApi" Version="1.0.0" />
+```
+
+Register OpenAPI services:
+
+```csharp
+using CoreIdent.OpenApi.Extensions;
+
+builder.Services.AddCoreIdentOpenApi(options =>
+{
+    options.DocumentTitle = "My API";
+    options.DocumentVersion = "v1";
+    options.OpenApiRoute = "/openapi/v1.json";
+});
+```
+
+### 1.2.2 Map the OpenAPI endpoint
+
+```csharp
+using CoreIdent.OpenApi.Extensions;
+
+app.MapCoreIdentOpenApi();
+```
+
+This maps an endpoint equivalent to `MapOpenApi(...)` so that `GET /openapi/v1.json` returns the OpenAPI JSON document.
+
+### 1.2.3 Optional UI: Scalar (host-managed)
+
+To serve an interactive API reference UI, install `Scalar.AspNetCore` in your host app and map it alongside the OpenAPI JSON:
+
+```csharp
+using Scalar.AspNetCore;
+
+app.MapCoreIdentOpenApi();
+app.MapScalarApiReference();
+```
+
+
 ### What you get
 
 With defaults, CoreIdent maps:

docs/README_Detailed.md

@@ -73,6 +73,7 @@ This section is a placeholder for DEVPLAN 1.13.6.
 - **Aspire integration** — Health checks, distributed tracing, service defaults
 - **OpenTelemetry metrics** — `System.Diagnostics.Metrics` instrumentation
 - **Templates** — `coreident-api`, `coreident-server`, `coreident-api-fsharp`
+- **OpenAPI** — OpenAPI JSON document generation via `CoreIdent.OpenApi` (no built-in UI)
 
 ### Coming Next
 
@@ -91,6 +92,51 @@ CoreIdent includes passwordless flows:
 
 For the SMS OTP endpoint and configuration reference, see the Developer Guide section [4.8 Passwordless SMS OTP](Developer_Guide.md#48-passwordless-sms-otp-feature-13).
 
+---
+
+## OpenAPI documentation (Feature 1.13.10)
+
+CoreIdent can generate an OpenAPI JSON document for all mapped endpoints.
+
+- **Document generation**: `CoreIdent.OpenApi` (built on .NET 10 `Microsoft.AspNetCore.OpenApi`)
+- **UI**: host-managed (CoreIdent does not ship Swashbuckle / Swagger UI)
+
+### Minimal setup
+
+```csharp
+using CoreIdent.OpenApi.Extensions;
+
+builder.Services.AddCoreIdentOpenApi(options =>
+{
+    options.DocumentTitle = "CoreIdent API";
+    options.DocumentVersion = "v1";
+    options.OpenApiRoute = "/openapi/v1.json";
+});
+
+var app = builder.Build();
+
+app.MapCoreIdentEndpoints();
+app.MapCoreIdentOpenApi();
+```
+
+### Optional UI (Scalar)
+
+In the host app:
+
+```bash
+dotnet add package Scalar.AspNetCore
+```
+
+Then:
+
+```csharp
+using Scalar.AspNetCore;
+
+app.MapCoreIdentOpenApi();
+app.MapScalarApiReference();
+```
+
+
 ## Documentation
 
 All planning and technical documentation is in the [`docs/`](./) folder:

src/CoreIdent.Core/Endpoints/TokenEndpointExtensions.cs

@@ -50,7 +50,11 @@ public static IEndpointRouteBuilder MapCoreIdentTokenEndpoint(this IEndpointRout
         ArgumentNullException.ThrowIfNull(endpoints);
         ArgumentException.ThrowIfNullOrWhiteSpace(tokenPath);
 
-        endpoints.MapPost(tokenPath, HandleTokenRequest);
+        endpoints
+            .MapPost(tokenPath, HandleTokenRequest)
+            .Produces<TokenResponse>(StatusCodes.Status200OK, "application/json")
+            .Produces<TokenErrorResponse>(StatusCodes.Status400BadRequest, "application/json")
+            .Produces<TokenErrorResponse>(StatusCodes.Status401Unauthorized, "application/json");
 
         return endpoints;
     }

src/CoreIdent.Core/Endpoints/TokenManagementEndpointsExtensions.cs

@@ -60,7 +60,8 @@ public static IEndpointRouteBuilder MapCoreIdentTokenManagementEndpoints(this IE
 
         ArgumentException.ThrowIfNullOrWhiteSpace(introspectPath);
 
-        endpoints.MapPost(revokePath, async (
+        endpoints
+            .MapPost(revokePath, async (
             HttpRequest request,
             ISigningKeyProvider signingKeyProvider,
             ITokenRevocationStore tokenRevocationStore,
@@ -171,10 +172,15 @@ public static IEndpointRouteBuilder MapCoreIdentTokenManagementEndpoints(this IE
                 logger.LogError(ex, "Error processing token revocation request.");
                 return Results.Json(new { error = "server_error", error_description = "An error occurred processing the request." }, statusCode: StatusCodes.Status500InternalServerError);
             }
-        });
+        })
+            .Produces(StatusCodes.Status200OK)
+            .Produces<TokenErrorResponse>(StatusCodes.Status400BadRequest, "application/json")
+            .Produces<TokenErrorResponse>(StatusCodes.Status401Unauthorized, "application/json")
+            .Produces<TokenErrorResponse>(StatusCodes.Status500InternalServerError, "application/json");
 
         // Introspection endpoint (RFC 7662)
-        endpoints.MapPost(introspectPath, async (
+        endpoints
+            .MapPost(introspectPath, async (
             HttpRequest request,
             ISigningKeyProvider signingKeyProvider,
             ITokenRevocationStore tokenRevocationStore,
@@ -270,7 +276,11 @@ public static IEndpointRouteBuilder MapCoreIdentTokenManagementEndpoints(this IE
 
             // Unknown token
             return Results.Json(new TokenIntrospectionResponse { Active = false });
-        });
+        })
+            .Produces<TokenIntrospectionResponse>(StatusCodes.Status200OK, "application/json")
+            .Produces<TokenErrorResponse>(StatusCodes.Status400BadRequest, "application/json")
+            .Produces<TokenErrorResponse>(StatusCodes.Status401Unauthorized, "application/json")
+            .Produces<TokenErrorResponse>(StatusCodes.Status500InternalServerError, "application/json");
 
         return endpoints;
     }

src/CoreIdent.Core/Endpoints/UserInfoEndpointExtensions.cs

@@ -46,7 +46,11 @@ public static IEndpointRouteBuilder MapCoreIdentUserInfoEndpoint(this IEndpointR
         ArgumentNullException.ThrowIfNull(endpoints);
         ArgumentException.ThrowIfNullOrWhiteSpace(userInfoPath);
 
-        endpoints.MapGet(userInfoPath, HandleUserInfoAsync);
+        endpoints
+            .MapGet(userInfoPath, HandleUserInfoAsync)
+            .Produces<UserInfoResponse>(StatusCodes.Status200OK, "application/json")
+            .Produces(StatusCodes.Status401Unauthorized)
+            .Produces(StatusCodes.Status403Forbidden);
 
         return endpoints;
     }

src/CoreIdent.OpenApi/Configuration/CoreIdentOpenApiOptions.cs

@@ -0,0 +1,32 @@
+namespace CoreIdent.OpenApi.Configuration;
+
+/// <summary>
+/// Options for configuring CoreIdent OpenAPI document generation.
+/// </summary>
+public sealed class CoreIdentOpenApiOptions
+{
+    /// <summary>
+    /// The OpenAPI document title.
+    /// </summary>
+    public string DocumentTitle { get; set; } = "CoreIdent API";
+
+    /// <summary>
+    /// The OpenAPI document version.
+    /// </summary>
+    public string DocumentVersion { get; set; } = "v1";
+
+    /// <summary>
+    /// The HTTP route where the OpenAPI JSON document is served.
+    /// </summary>
+    public string OpenApiRoute { get; set; } = "/openapi/v1.json";
+
+    /// <summary>
+    /// When <see langword="true"/>, include XML documentation (when available) in the generated OpenAPI document.
+    /// </summary>
+    public bool IncludeXmlComments { get; set; } = true;
+
+    /// <summary>
+    /// When <see langword="true"/>, include OpenAPI security scheme definitions in the document.
+    /// </summary>
+    public bool IncludeSecurityDefinitions { get; set; } = true;
+}

src/CoreIdent.OpenApi/CoreIdent.OpenApi.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <LangVersion>14</LangVersion>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.1" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\CoreIdent.Core\CoreIdent.Core.csproj" />
+  </ItemGroup>
+
+</Project>