DotNetOpenApiExtract 0.15.0

DotNetOpenApiExtract

CLI tool that extracts OpenAPI specifications from compiled .NET assemblies (DLL + XML docs) using static reflection — no application startup required.

Installation

dotnet tool install -g DotNetOpenApiExtract

Usage

dotnet openapi-extract --assembly bin/Debug/net9.0/MyApi.dll --output openapi.json

Why

Standard OpenAPI generation tools (swagger tofile, Microsoft.AspNetCore.OpenApi) require the application to fully start — which means a real database, message queues, external APIs, background services, and all environment variables must be available. Without infrastructure, the app crashes and the spec is never generated.

DotNetOpenApiExtract solves this by reading metadata directly from the compiled DLL via MetadataLoadContext. It never executes any code from your assembly. All it needs is the build output directory.

This means you can generate OpenAPI specs:

• In CI/CD without any infrastructure
• On developer machines without Docker or databases running
• From any .NET version (6, 7, 8, 9, 10) assembly

CLI Parameters

Validation flags

Validation

Running --validate checks the extracted spec against 52 completeness rules — 27 errors + 16 warnings always-on + 9 warnings off-by-default.

Typical CI usage:

# Block on errors, ignore warnings
dotnet openapi-extract --assembly bin/Debug/net9.0/MyApi.dll --validate

# Strict: block on any violation including warnings
dotnet openapi-extract --assembly bin/Debug/net9.0/MyApi.dll --validate --strict

# Skip a noisy rule
dotnet openapi-extract --assembly bin/Debug/net9.0/MyApi.dll --validate --skip-rule schema.required-consistency

# Enforce 422 on mutating endpoints (your org convention)
dotnet openapi-extract --assembly bin/Debug/net9.0/MyApi.dll --validate \
  --enable-rule operation.has-required-response-codes \
  --require-response-code mutating:422

# Different min-length per rule
dotnet openapi-extract --assembly bin/Debug/net9.0/MyApi.dll --validate \
  --min-description-length 10 \
  --rule-min-length enum.value-description:3 \
  --rule-min-length operation.description:30

# JSON report for tooling/agents
dotnet openapi-extract --assembly bin/Debug/net9.0/MyApi.dll --validate --validation-report report.json

Standalone validation — validate an existing spec file without extracting:

dotnet openapi-extract validate --spec openapi.json --validation-report report.json

All severity/skip/enable flags apply to both modes. Run dotnet openapi-extract --help and dotnet openapi-extract validate --help for the full rule list with per-rule severities.

What It Extracts

• Controllers ([ApiController], ControllerBase inheritance)
• Routes ([Route], [HttpGet], [HttpPost], etc.) with full template resolution
• Parameters ([FromRoute], [FromQuery], [FromBody], [FromHeader], [FromForm]) with [ApiController] inference
• Responses ([ProducesResponseType], [SwaggerResponse]) with return type inference
• Schemas from DTO classes — primitives, nullable, collections, dictionaries, enums, generics, inheritance, self-referencing types
• Enum extensions: x-enum-varnames (always, matches enum[] length), x-enum-descriptions (when any value is documented), markdown auto-glue description combining type summary + per-value bullet list
• Enum value description sources: XML <summary> (primary) with [Description] attribute fallback
• Validation attributes ([Required], [StringLength], [Range], [RegularExpression], etc.)
• JSON attributes ([JsonPropertyName], [JsonIgnore], [JsonRequired])
• Swagger annotations ([SwaggerOperation], [SwaggerParameter], [SwaggerTag], [SwaggerSchema])
• XML documentation (<summary>, <remarks>, <param>, <response>)
• Nullable reference types via NRT attribute analysis
• Description fallback chains: Swagger attrs > [Description] > XML docs
• [Obsolete] → deprecated: true on operations, schemas, enums
• API versioning ([ApiVersion], [MapToApiVersion], [ApiVersionNeutral]) as x-api-version extension
• Rate limiting ([EnableRateLimiting], [DisableRateLimiting]) as x-rate-limit-* extensions
• Response caching ([ResponseCache], [OutputCache]) as Cache-Control header description
• Well-known [JsonConverter] types (JsonStringEnumConverter, IsoDateTimeConverter, UnixDateTimeConverter, StringEnumConverter, etc.) mapped via built-in registry
• Per-endpoint security from [Authorize] / [AllowAnonymous] / [Authorize(AuthenticationSchemes=...)]

From Program.cs via Roslyn (when sources are available):

• Security schemes (AddSecurityDefinition, AddJwtBearer, AddSecurityRequirement) — including lambda-factory form
• UsePathBase("/prefix") — prepended to paths or emitted as servers[].url
• AddProblemDetails() — auto-injects default 400 / 422 / 500 responses with RFC 7807 ProblemDetails schema
• JSON serializer options (ConfigureHttpJsonOptions / AddJsonOptions): PropertyNamingPolicy, DictionaryKeyPolicy, DefaultIgnoreCondition, NumberHandling, global Converters.Add(...)
• Global response headers from middleware (app.Use(...), UseMiddleware<T>) — Response.Headers.Append/Add/TryAdd and indexer assignments
• Global [Consumes] / [Produces] from MVC filter registrations
• Document-level tags with descriptions + externalDocs from c.AddTag(...)
• FQN-prefixed types and enums (new Microsoft.OpenApi.OpenApiSecurityScheme { Type = Microsoft.OpenApi.SecuritySchemeType.ApiKey })
• In-project const string values via SemanticModel.GetConstantValue

For the complete catalog of 650+ supported attributes and constructs, see OpenAPI Attributes Catalog.

Limitations

Runtime-only Program.cs patterns

When analyzing Program.cs via Roslyn for security schemes, response headers, global options, etc., the tool recognizes common patterns but cannot resolve values known only at runtime.

These patterns are skipped silently (or with a warning to stderr). If your project relies heavily on runtime-resolved configuration, consider a Swashbuckle CLI tofile approach which executes the assembly partially instead of analyzing it statically.

Dependencies

Does not depend on: ASP.NET Core, Swashbuckle, Entity Framework, or any infrastructure packages.

Requirements

• .NET 10 SDK (to run the tool)
• The target assembly's build output directory with all reference DLLs (the tool needs them to resolve types)

Building

dotnet build
dotnet test

License

MIT