22. OpenAPI / Swagger

dotnet add package Swashbuckle.AspNetCore

// Program.csbuilder.Services.AddSwaggerGen(options =>{    options.SwaggerDoc("v1", new OpenApiInfo    {        Title = "Command API",        Version = "1.0.0",        Description = "API for managing commands and platforms"    });    // Document JWT authentication    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme    {        Type = SecuritySchemeType.Http,        Scheme = "bearer",        BearerFormat = "JWT",        Description = "JWT Authorization header"    });    options.AddSecurityRequirement(new OpenApiSecurityRequirement    {        {            new OpenApiSecurityScheme            {                Reference = new OpenApiReference                {                    Type = ReferenceType.SecurityScheme,                    Id = "Bearer"                }            },            new string[] { }        }    });    // Document API Key authentication    options.AddSecurityDefinition("ApiKey", new OpenApiSecurityScheme    {        Type = SecuritySchemeType.ApiKey,        In = ParameterLocation.Header,        Name = "x-api-key",        Description = "API Key authentication"    });    options.AddSecurityRequirement(new OpenApiSecurityRequirement    {        {            new OpenApiSecurityScheme            {                Reference = new OpenApiReference                {                    Type = ReferenceType.SecurityScheme,                    Id = "ApiKey"                }            },            new string[] { }        }    });    // Include XML documentation    var xmlFile = Path.Combine(AppContext.BaseDirectory, "CommandAPI.xml");    if (File.Exists(xmlFile))        options.IncludeXmlComments(xmlFile);});var app = builder.Build();if (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI(options =>    {        options.SwaggerEndpoint("/swagger/v1/swagger.json", "CommandAPI v1");    });}app.MapControllers();app.Run();

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\CommandAPI.xml</DocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

[Route("api/[controller]")]
[ApiController]
[Authorize(AuthenticationSchemes = ApiKeyConstants.SchemeName)]
public class PlatformsController : ControllerBase
{
    /// <summary>
    /// Get all platforms with pagination
    /// </summary>
    /// <param name="pageIndex">Page number (1-based, default: 1)</param>
    /// <param name="pageSize">Items per page (default: 10)</param>
    /// <returns>Paginated list of platforms</returns>
    /// <response code="200">Successfully retrieved platforms</response>
    /// <response code="401">Unauthorized - invalid credentials</response>
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(PaginatedList<PlatformReadDto>))]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    public async Task<ActionResult<PaginatedList<PlatformReadDto>>> GetPlatforms(
        int pageIndex = 1,
        int pageSize = 10)
    {
        var platforms = await _repository.GetPlatformsAsync(pageIndex, pageSize);
        return Ok(_mapper.Map<PaginatedList<PlatformReadDto>>(platforms));
    }
    
    /// <summary>
    /// Get a specific platform by ID
    /// </summary>
    /// <param name="id">Platform ID</param>
    /// <returns>Platform with all details</returns>
    /// <response code="200">Platform found</response>
    /// <response code="404">Platform not found</response>
    /// <response code="401">Unauthorized</response>
    [HttpGet("{id}", Name = "GetPlatformById")]
    [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(PlatformReadDto))]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    public async Task<ActionResult<PlatformReadDto>> GetPlatformById(int id)
    {
        var platform = await _repository.GetPlatformByIdAsync(id);
        if (platform == null)
            return NotFound();
        return Ok(_mapper.Map<PlatformReadDto>(platform));
    }
    
    /// <summary>
    /// Create a new platform
    /// </summary>
    /// <param name="platformDto">Platform data to create</param>
    /// <returns>Created platform with generated ID</returns>
    /// <response code="201">Platform successfully created</response>
    /// <response code="400">Invalid input data</response>
    /// <response code="401">Unauthorized</response>
    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created, Type = typeof(PlatformReadDto))]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    public async Task<ActionResult<PlatformReadDto>> CreatePlatform(
        PlatformMutateDto platformDto)
    {
        var platform = _mapper.Map<Platform>(platformDto);
        platform.CreatedBy = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
        await _repository.CreatePlatformAsync(platform);
        await _repository.SaveChangesAsync();
        var readDto = _mapper.Map<PlatformReadDto>(platform);
        return CreatedAtRoute(nameof(GetPlatformById), new { id = readDto.Id }, readDto);
    }
}

public class PlatformMutateDto
{
    /// <summary>
    /// Name of the platform (e.g., Windows, Linux, Docker)
    /// </summary>
    /// <example>Docker</example>
    [Required(ErrorMessage = "Platform name is required")]
    [MaxLength(100)]
    public required string PlatformName { get; set; }
}

public class CommandMutateDto
{
    /// <summary>
    /// What this command does
    /// </summary>
    /// <example>Build Docker image</example>
    [Required]
    [MaxLength(250)]
    public required string HowTo { get; init; }
    
    /// <summary>
    /// The actual command to execute
    /// </summary>
    /// <example>docker build -t myapp .</example>
    [Required]
    public required string CommandLine { get; set; }
    
    /// <summary>
    /// Platform this command runs on
    /// </summary>
    /// <example>1</example>
    [Range(1, int.MaxValue)]
    public int PlatformId { get; set; }
}