GO — Healthy across the board

• Last commit 1d ago
• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 73% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Swashbuckle.AspNetCore is an OpenAPI/Swagger documentation generator and UI toolkit for ASP.NET Core APIs. It auto-generates beautiful, interactive Swagger UI and OpenAPI 3.0/3.1 JSON documents directly from your C# controller code and annotations, keeping docs always in sync with your API implementation without manual maintenance. Multi-project solution (Swashbuckle.AspNetCore.slnx) with a modular structure: a core SwaggerGen library (likely in src/) that performs the introspection and OpenAPI generation, SwaggerUI middleware that serves the embedded web UI, and CLI tooling. Configuration is centralized in Directory.Build.props and Directory.Packages.props, with documentation in /docs/ organized by feature (configure-and-customize-swaggergen.md, configure-and-customize-swagger.md, etc.).

ASP.NET Core backend developers and API teams who need to automatically generate living API documentation with an embedded UI for testing endpoints; also used by SDK generators targeting Swagger/OpenAPI specifications.

Production-ready and actively maintained. The project is a foundational NuGet package with significant ecosystem adoption (evidenced by the extensive GitHub workflows, semantic versioning, and comprehensive CI/CD pipeline in .github/workflows/). Recently released v10.0 with OpenAPI 3.1 support, showing active development. Honest note: v10 introduced breaking changes, so migration guidance exists but real-world impact depends on dependency depth.

Low operational risk for most users, but moderate integration risk: v10's upgrade to Microsoft.OpenApi 2.x caused breaking changes (see .github/workflows/release.yml and docs/migrating-to-v10.md), requiring careful testing when upgrading. Single maintainer/org concentration could delay critical bug fixes, though the project is well-established. Dependency on Microsoft.OpenApi 2.x versions means you inherit any breaking changes from that package.

Active maintenance with recent workflow updates for .NET SDK management (update-dotnet-sdk.yml), baseline test updates (update-baselines.ps1), and security scanning (codeql-analysis.yml, ossf-scorecard.yml). The project is preparing documentation updates (update-documentation.yml workflow) and managing dependencies via Dependabot (dependabot.yml). V10 migration guide (docs/migrating-to-v10.md) is current.

Clone and build: git clone https://github.com/domaindrivendev/Swashbuckle.AspNetCore.git && cd Swashbuckle.AspNetCore && powershell build.ps1 (Windows) or ./build.ps1 (Linux/Mac with PowerShell Core installed). Check global.json for required .NET SDK version. Use dotnet restore to restore NuGet packages managed by Directory.Packages.props.

Daily commands: powershell build.ps1 for full build and test. For development, use dotnet build to compile the solution, then reference Swashbuckle packages in a test ASP.NET Core project. The repo itself is a library/toolkit, not a runnable application—you use it by installing NuGet packages and configuring it in your own ASP.NET Core project.

• src/Swashbuckle.AspNetCore.Annotations/AnnotationsDocumentFilter.cs — Core document-level filter that applies Swagger annotations to OpenAPI specification generation
• src/Swashbuckle.AspNetCore.Annotations/AnnotationsOperationFilter.cs — Essential operation filter that decorates API endpoints with Swagger metadata from attributes
• src/Shared/JsonSchemaTypes.cs — Shared JSON schema type definitions used across all schema generation and validation logic
• src/Swashbuckle.AspNetCore.ApiTesting/ApiTestRunnerBase.cs — Base class for API testing infrastructure that validates responses against OpenAPI specifications
• Directory.Build.props — Centralized MSBuild configuration defining dependencies, versions, and build properties for all projects
• .github/workflows/build.yml — Primary CI/CD pipeline orchestrating builds, tests, and code quality checks on every commit

Add Custom Operation Documentation

1. Create a SwaggerOperationAttribute on your controller action (src/Swashbuckle.AspNetCore.Annotations/SwaggerOperationAttribute.cs)
2. Register the AnnotationsOperationFilter in SwaggerGen configuration (src/Swashbuckle.AspNetCore.Annotations/AnnotationsSwaggerGenOptionsExtensions.cs)
3. The filter automatically processes your attributes during spec generation (src/Swashbuckle.AspNetCore.Annotations/AnnotationsOperationFilter.cs)

Add Custom Schema Annotations

1. Apply SwaggerSchemaAttribute to your model class (src/Swashbuckle.AspNetCore.Annotations/SwaggerSchemaAttribute.cs)
2. Register AnnotationsSchemaFilter in SwaggerGen options (src/Swashbuckle.AspNetCore.Annotations/AnnotationsSwaggerGenOptionsExtensions.cs)
3. The filter reads schema attributes and modifies the JSON schema representation (src/Swashbuckle.AspNetCore.Annotations/AnnotationsSchemaFilter.cs)

Implement API Response Validation

1. Subclass ApiTestRunnerBase to define your test infrastructure (src/Swashbuckle.AspNetCore.ApiTesting/ApiTestRunnerBase.cs)
2. Configure validation rules via ApiTestRunnerOptions (src/Swashbuckle.AspNetCore.ApiTesting/ApiTestRunnerOptions.cs)
3. Use JsonContentValidator to validate response bodies against the OpenAPI spec (src/Swashbuckle.AspNetCore.ApiTesting/JsonContentValidator.cs)

Add Custom Document-Level Metadata

1. Apply SwaggerTagAttribute for tagging support (src/Swashbuckle.AspNetCore.Annotations/SwaggerTagAttribute.cs)
2. Register AnnotationsDocumentFilter in SwaggerGen (src/Swashbuckle.AspNetCore.Annotations/AnnotationsSwaggerGenOptionsExtensions.cs)
3. The filter applies document-level transformations from annotations (src/Swashbuckle.AspNetCore.Annotations/AnnotationsDocumentFilter.cs)

• ASP.NET Core — Native integration with ASP.NET Core middleware and dependency injection; allows introspection of controller attributes at startup
• OpenAPI 3.0/3.1 & Swagger 2.0 — Industry-standard specification formats enabling tooling ecosystem compatibility and API contract documentation
• Swagger UI (embedded) — Provides interactive API exploration and testing UI without external dependencies; stays synchronized with generated spec
• Reflection & Attributes — Enables declarative, code-centric documentation without separate configuration files or DSLs
• JSON Schema validation — Standardized format for validating API responses against specification at runtime

• Attribute-based annotations rather than external config files

  • Why: Keeps documentation collocated with code; easier to maintain as code evolves
  • Consequence: Developers must decorate every operation; verbose for large APIs without proper conventions

• Runtime validation via ApiTestRunner rather than compile-time contracts

  • Why: Catches real-world deviations in actual responses without changing handler signatures
  • Consequence: Validation errors discovered only at test time, not at compile time; performance overhead during testing

• Separate projects for Annotations, ApiTesting, and core SwaggerGen

  • Why: Allows independent adoption; teams can use only the features they need
  • Consequence: Increased complexity managing inter-project dependencies and version alignment

• Embedded Swagger UI over CDN-hosted version

  • Why: No external network calls required; works offline; single assembly deployment
  • Consequence: Larger assembly size; must manually update when new Swagger UI versions released

• Does not generate server-side code or client SDKs from OpenAPI specs
• Does not handle authentication/authorization enforcement (documents it, doesn't secure it)
• Does not provide runtime API gateway or proxy functionality
• Does not support AsyncAPI or non-REST API patterns natively
• Does not perform semantic versioning or backwards compatibility checks on spec changes

Build requires PowerShell (see .github/bump-version.ps1, build.ps1, benchmark.ps1) — Windows developers have it built-in, but Linux/Mac need PowerShell Core installed. The project uses Directory.Packages.props for centralized version management; manually editing .csproj version tags will be overridden. Microsoft.OpenApi 2.x has hard dependency constraints that may conflict with older Swagger-related packages in your consuming project. The v10 breaking change is non-obvious: if you inherit this package transitively, you may suddenly require the new Microsoft.OpenApi 2.x without realizing it. SpectralRules (.spectral.yaml) are used for API lint validation — PRs may fail if OpenAPI examples don't conform. The repo uses Git blame ignore rules (.git-blame-ignore-revs) for style/formatting commits; be aware when investigating blame history.

• OpenAPI (formerly Swagger) Specification — Swashbuckle's entire purpose is to generate OpenAPI 3.0/3.1 documents; understanding the spec structure (paths, schemas, operations, components) is required to debug generation bugs or customize output
• Reflection-based Schema Generation — Swashbuckle uses .NET reflection on controller methods and type signatures to infer OpenAPI schemas; understanding how it traverses CLR types and attributes is key to debugging schema inference bugs
• ASP.NET Core Middleware Pipeline & Routing — Swashbuckle integrates as middleware and depends on ASP.NET Core's routing to discover endpoints; understanding how app.UseSwagger() fits into the request pipeline is essential for integration issues
• Operation Filters & Schema Filters (Plugin Architecture) — Swashbuckle's extensibility model uses operation and schema filters to allow customization of generated OpenAPI; knowing this pattern is critical for adding custom logic or overriding defaults
• JSON Schema (2020-12 in OpenAPI 3.1) — Swashbuckle v10+ upgraded to support OpenAPI 3.1, which uses JSON Schema 2020-12 instead of JSON Schema Draft 4; schema generation logic changed significantly, affecting validation and client generation
• Semantic Versioning & Breaking Changes Management — V10 introduced breaking changes (Microsoft.OpenApi 2.x upgrade); understanding how the team manages semver and migration paths helps you plan upgrades and understand the bump-version.ps1 release automation

• swagger-api/swagger-ui — The embedded UI that Swashbuckle serves; understanding swagger-ui's JavaScript configuration options is essential for Swagger UI customization in this repo
• OAI/OpenAPI-Specification — The specification Swashbuckle generates against; knowing the OpenAPI 3.0/3.1 spec is critical for understanding schema generation correctness
• microsoft/OpenAPI.NET — The underlying Microsoft.OpenApi NuGet package that Swashbuckle depends on for OpenAPI document serialization; v2.x breaking changes directly impact Swashbuckle's implementation
• Redocly/redoc — Alternative API documentation renderer supported by Swashbuckle; used via the ReDoc integration for teams preferring a different UI/UX
• dotnet/aspnetcore — The ASP.NET Core framework itself that Swashbuckle introspects; understanding how controllers, attributes, and endpoints work in ASP.NET Core is foundational

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for AnnotationsSchemaFilter and related annotation filters

The Annotations module (src/Swashbuckle.AspNetCore.Annotations/) lacks visible test coverage. AnnotationsSchemaFilter, AnnotationsOperationFilter, AnnotationsParameterFilter, and AnnotationsRequestBodyFilter are core components that transform metadata into OpenAPI specifications. Adding targeted unit tests would improve maintainability and catch regressions early, especially given the complexity of schema generation and validation.

• [ ] Create test project structure mirroring src/Swashbuckle.AspNetCore.Annotations/
• [ ] Add unit tests for AnnotationsSchemaFilter.cs covering custom attributes, schema modifications, and edge cases
• [ ] Add unit tests for AnnotationsOperationFilter.cs testing operation-level annotations and merging logic
• [ ] Add unit tests for AnnotationsParameterFilter.cs and AnnotationsRequestBodyFilter.cs
• [ ] Integrate new tests into .github/workflows/build.yml for CI/CD validation

Add OpenAPI 3.1 schema validation workflow to prevent spec regressions

The repo supports OpenAPI 3.0/3.1 but lacks a dedicated CI workflow to validate generated OpenAPI documents against the official OpenAPI 3.1 JSON Schema. This prevents subtle spec violations from being merged. The existing .github/workflows structure suggests room for a new validation pipeline using spectral-cli (already configured in .spectral.yaml).

• [ ] Create .github/workflows/openapi-validation.yml that runs on pull requests
• [ ] Configure the workflow to generate OpenAPI specs from test APIs
• [ ] Add spectral linting step using existing .spectral.yaml configuration
• [ ] Integrate official OpenAPI 3.1 schema validation (e.g., via json-schema-validator)
• [ ] Document the validation rules in CONTRIBUTING.md with specific examples

Add integration tests for XML comments parsing across .NET versions

The repo includes XmlCommentsBenchmark.cs in perf/ but lacks dedicated integration tests for XML documentation comment parsing behavior. Given the benchmark exists and CONTRIBUTING.md references documentation, there's an opportunity to add tests validating XML comment extraction works correctly across different parameter types, generics, and nullable reference types—critical since this affects API documentation quality.

• [ ] Create test project with sample APIs containing diverse XML comments (generics, nullables, enums)
• [ ] Add integration tests validating XmlCommentsSchemaFilter correctly extracts summary/remarks
• [ ] Add tests for parameter and operation-level XML comment extraction
• [ ] Test behavior across multiple target frameworks defined in Directory.Build.props
• [ ] Integrate into build.yml workflow to run against supported .NET versions

• Add missing C# XML documentation comments to public APIs in the SwaggerGen core project — many public methods lack <summary> tags, making IntelliSense unhelpful for library consumers. Check the src/ folder for undocumented public classes and methods.
• Expand docs/configure-and-customize-swaggerui.md with concrete examples for customizing swagger-ui auth schemes and advanced CSS theming — current examples are basic and the swagger-ui 5.x+ feature parity isn't fully documented.
• Add integration tests for OpenAPI 3.1-specific features (e.g., JSON Schema 2020-12 validation, webhooks, discriminator properties) to verify the new Microsoft.OpenApi 2.x generation paths work end-to-end; test files likely live in a test/ or tests/ directory.

The Swashbuckle.AspNetCore repository demonstrates a mature security posture with a formal vulnerability disclosure policy, GitHub Security Advisories integration, and active CI/CD security workflows (CodeQL, Dependabot, OSSF Scorecard). However, there are opportunities for improvement: the embedded ReDoc dependency requires regular auditing, the SECURITY.md policy lacks detail on response timelines and severity classification, and there is no visible evidence of package signing or comprehensive dependency management documentation. The presence of .git-blame-ignore-revs, eslint/markdown linting, and automated scanning shows security-conscious development practices. Overall security risk is LOW to MEDIUM.

• Medium · Outdated Embedded Dependency - ReDoc — package.json - redoc dependency. The package.json specifies ReDoc version 2.5.2, which may contain known vulnerabilities. ReDoc is embedded and served by the application, making it part of the attack surface. No evidence of a dependency scanning or update policy is visible in the repository configuration. Fix: Regularly audit embedded dependencies using tools like npm audit or Dependabot. Update ReDoc to the latest stable version and implement automated dependency scanning in CI/CD pipelines.
• Medium · Missing SECURITY.md Details on Vulnerability Disclosure Timeline — SECURITY.md. While SECURITY.md exists and provides a reporting mechanism via GitHub Security Advisories, it lacks details on response timeframes, severity guidelines, or vulnerability disclosure timeline. This can lead to confusion about expected turnaround times. Fix: Enhance SECURITY.md with: (1) Expected response timeframe (e.g., 48 hours), (2) Severity classification scheme, (3) Disclosure timeline policy, (4) Point of contact or security email address.
• Low · No Evidence of Code Signing or Artifact Verification — .github/workflows/nuget-packages-published.yml, .github/workflows/release.yml. The repository structure shows NuGet package publication workflows and release processes, but there is no visible documentation or configuration for code signing of published packages or cryptographic verification of release artifacts. Fix: Implement package signing for NuGet packages using digital signatures. Document the signing process and provide public keys for verification. Consider implementing SBOM (Software Bill of Materials) generation.
• Low · Limited Visibility into Dependency Management Strategy — Directory.Packages.props, Directory.Build.props. While Directory.Packages.props exists (suggesting centralized version management), there is no visible policy documentation for handling transitive dependencies, CVE patching schedules, or dependency update cadence. Fix: Document the dependency management policy including: (1) update cadence, (2) CVE response process, (3) transitive dependency handling strategy. Ensure Dependabot or similar tools are configured with appropriate schedules.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/domaindrivendev/Swashbuckle.AspNetCore shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live domaindrivendev/Swashbuckle.AspNetCore repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/domaindrivendev/Swashbuckle.AspNetCore.

What it runs against: a local clone of domaindrivendev/Swashbuckle.AspNetCore — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in domaindrivendev/Swashbuckle.AspNetCore | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of domaindrivendev/Swashbuckle.AspNetCore. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/domaindrivendev/Swashbuckle.AspNetCore.git
#   cd Swashbuckle.AspNetCore
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of domaindrivendev/Swashbuckle.AspNetCore and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "domaindrivendev/Swashbuckle.AspNetCore(\\.git)?\\b" \\
  && ok "origin remote is domaindrivendev/Swashbuckle.AspNetCore" \\
  || miss "origin remote is not domaindrivendev/Swashbuckle.AspNetCore (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/Swashbuckle.AspNetCore.Annotations/AnnotationsDocumentFilter.cs" \\
  && ok "src/Swashbuckle.AspNetCore.Annotations/AnnotationsDocumentFilter.cs" \\
  || miss "missing critical file: src/Swashbuckle.AspNetCore.Annotations/AnnotationsDocumentFilter.cs"
test -f "src/Swashbuckle.AspNetCore.Annotations/AnnotationsOperationFilter.cs" \\
  && ok "src/Swashbuckle.AspNetCore.Annotations/AnnotationsOperationFilter.cs" \\
  || miss "missing critical file: src/Swashbuckle.AspNetCore.Annotations/AnnotationsOperationFilter.cs"
test -f "src/Shared/JsonSchemaTypes.cs" \\
  && ok "src/Shared/JsonSchemaTypes.cs" \\
  || miss "missing critical file: src/Shared/JsonSchemaTypes.cs"
test -f "src/Swashbuckle.AspNetCore.ApiTesting/ApiTestRunnerBase.cs" \\
  && ok "src/Swashbuckle.AspNetCore.ApiTesting/ApiTestRunnerBase.cs" \\
  || miss "missing critical file: src/Swashbuckle.AspNetCore.ApiTesting/ApiTestRunnerBase.cs"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/domaindrivendev/Swashbuckle.AspNetCore"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.