关于Swagger依赖环境配置的技术疑问：为何需全环境添加Swagger依赖仅在开发环境启用UI？

Great question! It makes total sense to wonder why we don’t wrap builder.Services.AddSwaggerGen() in the same if (app.Environment.IsDevelopment()) block as the Swagger UI middleware. Let’s break down the core reasons behind the official recommendation, plus when you might choose a different approach.

1. Swagger isn’t just the UI—OpenAPI documents have production use cases #

AddSwaggerGen() is responsible for generating the OpenAPI specification document (the raw JSON/YAML that describes your API), not just powering the interactive UI. This document has valuable uses beyond development:

• You might expose the raw /swagger/v1/swagger.json endpoint in production for third-party integrations, API gateways, or automated client SDK generation.
• Teams often use this spec to feed into documentation tools or contract testing pipelines, even in non-development environments.

If you only register AddSwaggerGen() in development, you’d have to duplicate that configuration if you ever need the spec in staging or production. Globally registering it keeps this configuration consistent across all environments.

2. Minimal overhead vs. maximum flexibility #

The Swashbuckle NuGet packages (which power Swagger in .NET) are lightweight, so leaving AddSwaggerGen() registered globally adds negligible overhead to production deployments. The official approach prioritizes flexibility:

• You can enable just the raw spec endpoint in staging without rewriting configuration.
• You avoid the complexity of conditional NuGet package references (which would be required if you wanted to exclude Swagger dependencies entirely from production builds).

Here’s an example of how you might use the global registration to expose the spec in staging while hiding the UI:

// Global registration (same for all environments)
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    // Add shared configuration like XML comments, security schemes, etc.
});

// Environment-specific middleware setup
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}
else if (app.Environment.IsStaging())
{
    // Expose only the raw spec, no UI
    app.UseSwagger();
}

3. Simplified configuration maintenance #

By keeping AddSwaggerGen() global, you define your API documentation rules once—things like XML comment inclusion, OAuth2 security definitions, or API versioning settings—instead of duplicating that code across environment-specific blocks. This reduces the chance of configuration drift between environments.

When would you restrict AddSwaggerGen() to development? #

If you’re absolutely certain you’ll never need the OpenAPI spec outside development, and you want to eliminate even the tiny overhead of Swagger dependencies in production, you can:

1. Use conditional NuGet references in your .csproj file to include Swashbuckle packages only in development.
2. Wrap AddSwaggerGen() in the same environment check as the UI middleware.

That said, this adds extra complexity to your project setup, and the tradeoff rarely justifies the minimal gains for most applications.

内容的提问来源于stack exchange，提问作者VladOhotnikov