|
| 1 | +# Coding Agent Instructions |
| 2 | + |
| 3 | +This file provides guidance to agents when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +Swashbuckle.AspNetCore is an OpenAPI (Swagger) tooling library for ASP.NET Core. It generates OpenAPI 2.0/3.0/3.1 documents |
| 8 | +from ASP.NET Core routes/controllers/models at runtime, and serves the swagger-ui and ReDoc UIs as embedded middleware. |
| 9 | + |
| 10 | +It targets the currently released and supported versions of .NET. |
| 11 | + |
| 12 | +## Commands |
| 13 | + |
| 14 | +**Build and test (full pipeline):** |
| 15 | + |
| 16 | +```powershell |
| 17 | +./build.ps1 |
| 18 | +``` |
| 19 | + |
| 20 | +This runs `dotnet pack` followed by `dotnet test`. |
| 21 | + |
| 22 | +**Build only:** |
| 23 | + |
| 24 | +```bash |
| 25 | +dotnet build |
| 26 | +``` |
| 27 | + |
| 28 | +**Run all tests:** |
| 29 | + |
| 30 | +```bash |
| 31 | +dotnet test |
| 32 | +``` |
| 33 | + |
| 34 | +**Run tests for a specific project:** |
| 35 | + |
| 36 | +```bash |
| 37 | +dotnet test test/Swashbuckle.AspNetCore.SwaggerGen.Test/ |
| 38 | +dotnet test test/Swashbuckle.AspNetCore.IntegrationTests/ |
| 39 | +``` |
| 40 | + |
| 41 | +**Run a single test:** |
| 42 | + |
| 43 | +```bash |
| 44 | +dotnet test test/Swashbuckle.AspNetCore.SwaggerGen.Test/ --filter "FullyQualifiedName~MethodName" |
| 45 | +``` |
| 46 | + |
| 47 | +**Restore .NET tools:** |
| 48 | + |
| 49 | +```bash |
| 50 | +dotnet tool restore |
| 51 | +``` |
| 52 | + |
| 53 | +**Update snapshot files (Verify tests):** |
| 54 | + |
| 55 | +When snapshot-based tests fail due to intentional changes, update snapshots by running tests with the |
| 56 | +`VERIFY_AUTO_ACCEPT_CHANGES=true` environment variable or by accepting the diff via the Verify framework's mechanism. |
| 57 | + |
| 58 | +## Architecture |
| 59 | + |
| 60 | +### Source packages (`src/`) |
| 61 | + |
| 62 | +| Project | Purpose | |
| 63 | +| --- | --- | |
| 64 | +| `Swashbuckle.AspNetCore.Swagger` | Core middleware that serves OpenAPI JSON endpoints; depends on `Microsoft.OpenApi` | |
| 65 | +| `Swashbuckle.AspNetCore.SwaggerGen` | OpenAPI document generation engine — the main logic layer | |
| 66 | +| `Swashbuckle.AspNetCore.SwaggerUI` | Embeds swagger-ui as ASP.NET Core middleware (bundles from npm) | |
| 67 | +| `Swashbuckle.AspNetCore.ReDoc` | Embeds ReDoc as ASP.NET Core middleware (bundles from npm) | |
| 68 | +| `Swashbuckle.AspNetCore.Annotations` | Optional attributes (`SwaggerOperation`, `SwaggerResponse`, etc.) | |
| 69 | +| `Swashbuckle.AspNetCore.Newtonsoft` | Newtonsoft.Json support replacing the default System.Text.Json contract resolver | |
| 70 | +| `Swashbuckle.AspNetCore.Cli` | `dotnet swagger` CLI tool for offline document generation | |
| 71 | +| `Swashbuckle.AspNetCore.ApiTesting` | Assertion helpers for API contract testing | |
| 72 | +| `Swashbuckle.AspNetCore` | Meta-package referencing the above | |
| 73 | + |
| 74 | +### Key generation pipeline (`SwaggerGen`) |
| 75 | + |
| 76 | +1. **`SwaggerGenerator`** — entry point; uses `IApiDescriptionGroupCollectionProvider` (ASP.NET Core's API explorer) to enumerate endpoints, then calls `SchemaGenerator` for each type. |
| 77 | +2. **`SchemaGenerator`** — converts .NET types to `IOpenApiSchema` objects. Uses `ISerializerDataContractResolver` to understand how the serializer will represent types. |
| 78 | +3. **`JsonSerializerDataContractResolver`** — the default resolver backed by System.Text.Json; `NewtonsoftDataContractResolver` (in the Newtonsoft package) is the alternative. |
| 79 | +4. **`SchemaRepository`** — accumulates reusable schemas into `components/schemas` to avoid duplication. Schemas are referenced by `$ref` after first generation. |
| 80 | +5. **Filters** — `IDocumentFilter`, `IOperationFilter`, `IParameterFilter`, `IRequestBodyFilter`, `ISchemaFilter` (sync and async variants) are applied at each pipeline stage and are the primary extension points. |
| 81 | + |
| 82 | +### Test structure (`test/`) |
| 83 | + |
| 84 | +- `Swashbuckle.AspNetCore.SwaggerGen.Test` — unit tests for schema and swagger generation; uses xUnit v3 and Verify for snapshot testing; snapshots stored under `snapshots/{tfm}/`. |
| 85 | +- `Swashbuckle.AspNetCore.IntegrationTests` — end-to-end tests running real `WebApplication` instances; also uses Verify snapshots and Playwright for UI tests. |
| 86 | +- `WebSites/` — sample ASP.NET Core apps used as test fixtures (Basic, MinimalApp, MultipleVersions, OAuth2Integration, etc.). |
| 87 | +- `Swashbuckle.AspNetCore.TestSupport` — shared test helpers. |
| 88 | + |
| 89 | +### Public API tracking |
| 90 | + |
| 91 | +Packable projects use `Microsoft.CodeAnalysis.PublicApiAnalyzers`. Any change to the public API surface must be reflected in `PublicAPI/PublicAPI.Unshipped.txt` (and per-TFM variants). Breaking changes require a baseline comparison against `PackageValidationBaselineVersion`. |
| 92 | + |
| 93 | +### Warnings and strictness |
| 94 | + |
| 95 | +`TreatWarningsAsErrors` is enabled globally. `Nullable` annotations are not yet enabled. |
| 96 | + |
| 97 | +## Key conventions |
| 98 | + |
| 99 | +- Central package version management via `Directory.Packages.props`. |
| 100 | +- The primary serializer integration is System.Text.Json; Newtonsoft.Json is opt-in via the separate package. |
| 101 | +- Integration test snapshots under `test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/` are linted with Spectral in CI to validate OpenAPI correctness. |
| 102 | +- SwaggerUI and ReDoc bundles are managed via npm (`package.json` in their respective `src/` directories). |
| 103 | + |
| 104 | +## General guidelines |
| 105 | + |
| 106 | +- Always ensure code compiles with no warnings or errors and tests pass locally before pushing changes. |
| 107 | +- Do not change the public API unless specifically requested. |
| 108 | +- Do not use APIs marked with `[Obsolete]`. |
| 109 | +- Bug fixes should **always** include a test that would fail without the corresponding fix. |
| 110 | +- Do not introduce new dependencies unless specifically requested. |
| 111 | +- Do not update existing dependencies unless specifically requested. |
0 commit comments