01. Swagger/OpenAPI API Documentation

Level: Intermediate

ℹ️ What You'll Learn

• Why API documentation matters for frontend teams
• Install and configure Swagger/Swashbuckle
• Auto-generate API documentation
• Test endpoints interactively in Swagger UI
• Add XML comments for clear descriptions
• Export OpenAPI spec

The Problem

You build a .NET Web API for School Management System. Your frontend team needs to know: What endpoints exist? What data do they send? What response comes back? Swagger auto-generates beautiful, interactive documentation from your code, keeping docs in sync with your actual API.

Install Swashbuckle

In SMS.Api project:

dotnet add package Swashbuckle.AspNetCore

Configure Swagger

File: SMS.Api/Program.cs

builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.MapControllers();
app.Run();

Run API

dotnet run
# Visit: http://localhost:5000/swagger/index.html

Swagger UI shows all API endpoints automatically.

Document with XML Comments

File: SMS.Api/Controllers/StudentsController.cs

/// <summary>
/// Get student by ID
/// </summary>
/// <param name="id">Student ID</param>
/// <returns>Student details</returns>
[HttpGet("{id}")]
public async Task<ActionResult<Student>> GetStudent(int id)
{
    var student = await _service.GetStudentAsync(id);
    if (student == null)
        return NotFound();
    return Ok(student);
}

/// <summary>
/// Create new student
/// </summary>
/// <param name="student">Student data</param>
/// <returns>Created student</returns>
[HttpPost]
public async Task<ActionResult> CreateStudent([FromBody] Student student)
{
    await _service.CreateStudentAsync(student);
    return Created();
}

Enable XML documentation in project file:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Comments appear in Swagger UI.

Swagger Endpoint Examples

Get Students:

GET /api/students
Response: [{ id, name, rollNumber, className }]

Get Student by ID:

GET /api/students/101
Response: { id: 101, name: "Ravi", ... }

Create Student:

POST /api/students
Body: { name, rollNumber, className, status }
Response: 201 Created

Test directly in Swagger UI:

1. Click endpoint
2. Click "Try it out"
3. Enter values
4. Click "Execute"
5. See response

Export OpenAPI Spec

Visit: http://localhost:5000/swagger/v1/swagger.json

Download JSON spec. Share with frontend team.

Frontend uses spec to generate client libraries.

Key Takeaways

• Swagger = auto-generated documentation
• Live testing = test in browser
• XML comments = readable docs
• OpenAPI spec = machine-readable API

💡 Swagger Tip

Keep XML comments updated. Documentation should match code.

🤖Use AI to Learn Faster

Use ChatGPT, Claude, or Copilot to go deeper on Swagger Documentation. Try these prompts:

• "How do I add Swagger to ASP.NET Core?"
• "How do I document API endpoints?"
• "How do I test APIs in Swagger UI?"
• "Quiz me on Swagger"

💡 Tip: After reading this article, paste your own code into AI and ask "What could go wrong here and why?" — fastest way to find edge cases and deepen understanding.