add comments for swagger

AB-API/Program.cs

@@ -6,6 +6,7 @@ using AB.Services.Abstractions;
 using AB_API.Middleware;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.OpenApi.Models;
+using System.Reflection;
 using System.Text.Json.Serialization;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -17,7 +18,18 @@ builder.Services.AddControllers().AddApplicationPart(typeof(AB.API.AssemblyRefer
 
 // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
 builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddSwaggerGen(c => c.SwaggerDoc("v1", new OpenApiInfo { Title = "AB-API", Version = "v1", Description = "An Api for the AB-Application" }));
+builder.Services.AddSwaggerGen(c =>
+{
+    c.SwaggerDoc("v1", new OpenApiInfo
+    {
+        Title = "AB-API",
+        Version = "v1",
+        Description = "An Api for the AB-Application"
+    });
+
+    var xmlFilename = $"{typeof(AB.API.AssemblyReference).Assembly.GetName().Name}.xml";
+    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
+});
 
 builder.Services.AddScoped<ICustomerService, CustomerService>();
 builder.Services.AddScoped<ICustomerRepository, CustomerRepository>();

AB.API/AB.API.csproj

@@ -4,6 +4,7 @@
 		<TargetFramework>net6.0</TargetFramework>
 		<ImplicitUsings>enable</ImplicitUsings>
 		<Nullable>enable</Nullable>
+		<GenerateDocumentationFile>true</GenerateDocumentationFile>
 	</PropertyGroup>
 
 	<ItemGroup>

AB.API/Controllers/BusinessPartner/CustomerController.cs

@@ -1,11 +1,13 @@
 using AB.Contracts;
 using AB.Services.Abstractions;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 
 namespace AB.API.Controllers.BusinessPartner;
 
 [ApiController]
 [Route("api/customers")]
+[Produces("application/json")]
 public class CustomerController : ControllerBase
 {
 
@@ -16,6 +18,11 @@ public class CustomerController : ControllerBase
             _customerService = customerService;
     }
 
+    /// <summary>
+    /// Abrufen aller Kunden 
+    /// </summary>
+    /// <param name="cancellationToken"></param>
+    /// <returns>Eine Liste aller Kunden</returns>
     [HttpGet]
     public async Task<ActionResult<IEnumerable<CustomerDto>>> GetCustomers(CancellationToken cancellationToken)
     {
@@ -24,6 +31,12 @@ public class CustomerController : ControllerBase
         return Ok(customers);
     }
 
+    /// <summary>
+    /// Abrufen eines Kunden anhand seiner Id
+    /// </summary>
+    /// <param name="customerId"></param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>Den Kunden mit der angegeben Id</returns>
     [HttpGet("{customerId:guid}")]
     public async Task<ActionResult<CustomerDto>> GetCustomerById(Guid customerId, CancellationToken cancellationToken)
     {
@@ -32,7 +45,14 @@ public class CustomerController : ControllerBase
         return Ok(customer);
     }
 
+    /// <summary>
+    /// Anlegen eines neuen Kunden
+    /// </summary>
+    /// <param name="customerForCreation"></param>
+    /// <returns>Einen neu erstellten Kunden</returns>
+    /// <response code="201">Kunde wurde erstellt</response>
     [HttpPost]
+    [ProducesResponseType(StatusCodes.Status201Created)]
     public async Task<CreatedAtActionResult> CreateCustomer([FromBody] CustomerForCreationDto customerForCreation)
     {
         var customerDto = await _customerService.CreateAsync(customerForCreation);
@@ -40,7 +60,17 @@ public class CustomerController : ControllerBase
         return CreatedAtAction(nameof(CreateCustomer), new { customerId = customerDto.Id }, customerDto);
     }
 
+    /// <summary>
+    /// Löschen eines vorhandenen Kunden
+    /// </summary>
+    /// <param name="customerId"></param>
+    /// <param name="cancellationToken"></param>
+    /// <returns></returns>
+    /// <response code="204">Kunde wurde gelöscht</response>
+    /// <response code="404">Kunde wurde nicht gefunden</response>
     [HttpDelete("{customerId:guid}")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<NoContentResult> DeleteCustomer(Guid customerId, CancellationToken cancellationToken)
     {
         await _customerService.DeleteAsync(customerId, cancellationToken);
@@ -48,7 +78,19 @@ public class CustomerController : ControllerBase
         return NoContent();
     }
 
+    /// <summary>
+    /// Bearbeiten eines vorhanden Kunden
+    /// </summary>
+    /// <param name="customerId"></param>
+    /// <param name="customerForUpdate"></param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>Den veränderten Kunden
+    /// </returns>
+    /// <response code="200">Kunde wurde bearbeitet</response>
+    /// <response code="404">Kunde wurde nicht gefunden</response>
     [HttpPut("{customerId:guid}")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<ActionResult<CustomerDto>> UpdateCustomer(Guid customerId, CustomerForUpdateDto customerForUpdate, CancellationToken cancellationToken)
     {
         var customerDto = await _customerService.UpdateAsync(customerId, customerForUpdate, cancellationToken);

AB.API/Controllers/BusinessPartner/SupplierController.cs

@@ -1,11 +1,13 @@
 using AB.Contracts;
 using AB.Services.Abstractions;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 
 namespace AB.API.Controllers.BusinessPartner;
 
 [ApiController]
 [Route("api/suppliers")]
+[Produces("application/json")]
 public class SupplierController : ControllerBase
 {
 
@@ -16,6 +18,11 @@ public class SupplierController : ControllerBase
         _supplierService = supplierService;
     }
 
+    /// <summary>
+    /// Abrufen aller Lieferanten
+    /// </summary>
+    /// <param name="cancellationToken"></param>
+    /// <returns></returns>
     [HttpGet]
     public async Task<ActionResult<IEnumerable<SupplierDto>>> GetSupplieres(CancellationToken cancellationToken)
     {
@@ -24,7 +31,16 @@ public class SupplierController : ControllerBase
         return Ok(suppliers);
     }
 
+    /// <summary>
+    /// Abrufen eines Lieferanten anhand seiner Id
+    /// </summary>
+    /// <param name="supplierId"></param>
+    /// <param name="cancellationToken"></param>
+    /// <returns></returns>
+    /// <response code="404">Lieferant wurde nicht gefunden</response>
     [HttpGet("{supplierId:guid}")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<ActionResult<SupplierDto>> GetSupplierById(Guid supplierId, CancellationToken cancellationToken)
     {
         var supplierDto = await _supplierService.GetSupplierByIdAsync(supplierId, cancellationToken);
@@ -32,7 +48,15 @@ public class SupplierController : ControllerBase
         return Ok(supplierDto);
     }
 
+    /// <summary>
+    /// Anlegen eines neuen Lieferanten
+    /// </summary>
+    /// <param name="supplierForCreation"></param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>Einen neu erstellen Kunden</returns>
+    /// <response code="201">Lieferant wurde erstellt</response>
     [HttpPost]
+    [ProducesResponseType(StatusCodes.Status201Created)]
     public async Task<CreatedAtActionResult> CreateSupplier([FromBody] SupplierForCreationDto supplierForCreation, CancellationToken cancellationToken)
     {
         var supplierDto = await _supplierService.CreateAsync(supplierForCreation, cancellationToken);
@@ -40,7 +64,17 @@ public class SupplierController : ControllerBase
         return CreatedAtAction(nameof(CreateSupplier), new { id = supplierDto.Id }, supplierDto);
     }
 
+    /// <summary>
+    /// Löschen eines vorhanden Lieferanten
+    /// </summary>
+    /// <param name="supplierId"></param>
+    /// <param name="cancellationToken"></param>
+    /// <returns></returns>
+    /// <response code="204">Lieferant wurde gelöscht</response>
+    /// <response code="404">Lieferant wurde nicht gefunden</response>
     [HttpDelete("{supplierId:guid}")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<NoContentResult> DeleteSupplier(Guid supplierId, CancellationToken cancellationToken)
     {
         await _supplierService.DeleteAsync(supplierId, cancellationToken);