# Swagger Dotnet

> |

- **Type:** Skill
- **Install:** `agentstack add skill-claude-dev-suite-claude-dev-suite-swagger-dotnet`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [claude-dev-suite](https://agentstack.voostack.com/s/claude-dev-suite)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [claude-dev-suite](https://github.com/claude-dev-suite)
- **Source:** https://github.com/claude-dev-suite/claude-dev-suite/tree/main/skills/api-design/swagger-dotnet

## Install

```sh
agentstack add skill-claude-dev-suite-claude-dev-suite-swagger-dotnet
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Swagger for .NET - Quick Reference

> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `aspnet-core` for OpenAPI documentation.

## Swashbuckle Setup

```csharp
// Program.cs
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = "API for managing users and orders",
    });

    // XML comments
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);

    // JWT auth in Swagger UI
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "Enter JWT token",
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT",
        Scheme = "bearer",
    });
    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer",
                }
            },
            Array.Empty()
        }
    });
});

// Enable XML docs in .csproj
// true
```

## Controller Annotations

```csharp
/// 
/// Manages user resources
/// 
[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
[Tags("Users")]
public class UsersController : ControllerBase
{
    /// 
    /// Get user by ID
    /// 
    /// The user ID
    /// The user details
    /// Returns the user
    /// User not found
    [HttpGet("{id:int}")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task GetById(int id) { }

    /// 
    /// Create a new user
    /// 
    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task Create([FromBody] CreateUserRequest request) { }
}
```

## Operation Filters

```csharp
public class AddCorrelationIdHeader : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        operation.Parameters ??= new List();
        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "X-Correlation-Id",
            In = ParameterLocation.Header,
            Required = false,
            Schema = new OpenApiSchema { Type = "string" },
        });
    }
}

// Register
options.OperationFilter();
```

## NSwag Alternative

```csharp
// Install: dotnet add package NSwag.AspNetCore
builder.Services.AddOpenApiDocument(config =>
{
    config.Title = "My API";
    config.Version = "v1";
    config.AddSecurity("Bearer", new NSwag.OpenApiSecurityScheme
    {
        Type = NSwag.OpenApiSecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
    });
});

app.UseOpenApi();
app.UseSwaggerUi();
```

## Anti-Patterns

| Anti-Pattern | Why It's Bad | Correct Approach |
|--------------|--------------|------------------|
| No response type annotations | Incomplete docs | Use `[ProducesResponseType]` |
| Missing XML comments | No descriptions | Enable and write XML docs |
| Swagger in production | Security risk | Conditionally enable for dev |
| No auth scheme in docs | Can't test auth endpoints | Add security definition |

## Quick Troubleshooting

| Issue | Likely Cause | Solution |
|-------|--------------|----------|
| No XML comments | Not enabled | Add `` |
| Missing endpoint | Wrong route | Check `[Route]` attributes |
| Auth not working in UI | Missing security definition | Add `AddSecurityDefinition` |
| Schema conflicts | Duplicate type names | Use `SchemaId` configuration |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [claude-dev-suite](https://github.com/claude-dev-suite)
- **Source:** [claude-dev-suite/claude-dev-suite](https://github.com/claude-dev-suite/claude-dev-suite)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-claude-dev-suite-claude-dev-suite-swagger-dotnet
- Seller: https://agentstack.voostack.com/s/claude-dev-suite
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.