update swagger

src/Altinn.Broker.API/Altinn.Broker.API.csproj

@@ -4,6 +4,8 @@
     <TargetFramework>net9.0</TargetFramework>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Altinn.Broker.API/Controllers/FileTransferController.cs

@@ -33,12 +33,20 @@ public class FileTransferController(ILogger<FileTransferController> logger, IIde
 {
 
     /// <summary>
-    /// Initialize a file transfer and file upload
+    /// Initialize a file transfer
     /// </summary>
+    /// <remarks>
+    /// Scopes: <br />
+    /// - altinn:broker.write
+    /// </remarks>
     /// <returns></returns>
     [HttpPost]
     [Authorize(Policy = AuthorizationConstants.Sender)]
     [Produces("application/json")]
+    [ProducesResponseType(typeof(FileTransferInitializeResponseExt), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status503ServiceUnavailable)]
     public async Task<ActionResult<Guid>> InitializeFileTransfer(FileTransferInitalizeExt initializeExt, [FromServices] InitializeFileTransferHandler handler, CancellationToken cancellationToken)
     {
         LogContextHelpers.EnrichLogsWithInitializeFile(initializeExt);
@@ -58,11 +66,19 @@ public async Task<ActionResult<Guid>> InitializeFileTransfer(FileTransferInitali
     /// <summary>
     /// Upload to an initialized file using a binary stream.
     /// </summary>
+    /// <remarks>
+    /// Scopes: <br />
+    /// - altinn:broker.write
+    /// </remarks>
     /// <returns></returns>
     [HttpPost]
     [Route("{fileTransferId}/upload")]
     [Consumes("application/octet-stream")]
     [Produces("application/json")]
+    [ProducesResponseType(typeof(FileTransferUploadResponseExt), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status503ServiceUnavailable)]
     [Authorize(Policy = AuthorizationConstants.Sender)]
     public async Task<ActionResult> UploadStreamed(
         Guid fileTransferId,
@@ -92,10 +108,21 @@ CancellationToken cancellationToken
     }
 
     /// <summary>
-    /// Initialize and upload a file using form-data
+    /// Initialize a filetransfer and uploads the file in the same request using form-data
     /// </summary>
+    /// <remarks>
+    /// Scopes: <br />
+    /// - altinn:broker.write
+    /// </remarks>
     /// <returns></returns>
     [HttpPost]
+    [Consumes("multipart/form-data")]
+    [Produces("application/json")]
+    [ProducesResponseType(typeof(string), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status409Conflict)]
+    [ProducesResponseType(StatusCodes.Status503ServiceUnavailable)]
     [Route("upload")]
     [RequestFormLimits(MultipartBodyLengthLimit = long.MaxValue)]
     [Authorize(Policy = AuthorizationConstants.Sender)]
@@ -129,12 +156,20 @@ CancellationToken cancellationToken
     }
 
     /// <summary>
-    /// Get information about the file and its current status
+    /// Get information about the file transfer and its current status
     /// </summary>
+    /// <remarks>
+    /// Scopes: <br />
+    /// - altinn:broker.read <br/>
+    /// - altinn:broker.write
+    /// </remarks>
     /// <returns></returns>
     [HttpGet]
     [Route("{fileTransferId}")]
     [Produces("application/json")]
+    [ProducesResponseType(typeof(FileTransferOverviewExt), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Authorize(Policy = AuthorizationConstants.SenderOrRecipient)]
     public async Task<ActionResult<FileTransferOverviewExt>> GetFileTransferOverview(
         Guid fileTransferId,
@@ -153,12 +188,20 @@ public async Task<ActionResult<FileTransferOverviewExt>> GetFileTransferOverview
     }
 
     /// <summary>
-    /// Get more detailed information about the file upload for auditing and troubleshooting purposes
+    /// Get more detailed information about the file transfer for auditing and troubleshooting purposes
     /// </summary>
+    /// <remarks>
+    /// Scopes: <br />
+    /// - altinn:broker.read <br/>
+    /// - altinn:broker.write
+    /// </remarks>
     /// <returns></returns>
     [HttpGet]
     [Route("{fileTransferId}/details")]
     [Produces("application/json")]
+    [ProducesResponseType(typeof(FileTransferStatusDetailsExt), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Authorize(Policy = AuthorizationConstants.SenderOrRecipient)]
     public async Task<ActionResult<FileTransferStatusDetailsExt>> GetFileTransferDetails(
         Guid fileTransferId,
@@ -178,12 +221,22 @@ public async Task<ActionResult<FileTransferStatusDetailsExt>> GetFileTransferDet
     }
 
     /// <summary>
-    /// Get files that can be accessed by the caller according to specified filters. Result set is limited to 100 files. If your query returns more than 100 files, you will only receive the 100 last created.
+    /// Get files that can be accessed by the caller according to specified filters
     /// </summary>
+    /// <remarks>
+    /// Scopes: <br />
+    /// - altinn:broker.read <br/>
+    /// - altinn:broker.write <br/>
+    /// Result is limited to 100 files. If your query returns more than 100 files, you will only receive the 100 last created.
+    /// </remarks>
     /// <returns></returns>
     [HttpGet]
     [Authorize(Policy = AuthorizationConstants.SenderOrRecipient)]
     [Produces("application/json")]
+    [ProducesResponseType(typeof(List<Guid>), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
     public async Task<ActionResult<List<Guid>>> GetFileTransfers(
         [FromQuery] string resourceId,
         [FromQuery] FileTransferStatusExt? status,
@@ -211,8 +264,18 @@ public async Task<ActionResult<List<Guid>>> GetFileTransfers(
     /// <summary>
     /// Downloads the file
     /// </summary>
+    /// <remarks>
+    /// Scopes: <br />
+    /// - altinn:broker.read <br/>
+    /// </remarks>
     /// <returns></returns>
     [HttpGet]
+    [Produces("application/octet-stream")]
+    [ProducesResponseType(typeof(FileStreamResult), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Route("{fileTransferId}/download")]
     [Authorize(Policy = AuthorizationConstants.Recipient)]
     public async Task<ActionResult> DownloadFile(
@@ -234,8 +297,18 @@ public async Task<ActionResult> DownloadFile(
     /// <summary>
     /// Confirms that the file has been downloaded
     /// </summary>
+    /// <remarks>
+    /// Scopes: <br/> 
+    /// - altinn:broker.read <br/>
+    /// </remarks>
     /// <returns></returns>
     [HttpPost]
+    [Produces("application/json")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Route("{fileTransferId}/confirmdownload")]
     [Authorize(Policy = AuthorizationConstants.Recipient)]
     public async Task<ActionResult> ConfirmDownload(

src/Altinn.Broker.API/Controllers/HealthController.cs

@@ -6,6 +6,7 @@ namespace Altinn.Broker.Controllers;
 
 [ApiController]
 [Route("health")]
+[ApiExplorerSettings(IgnoreApi = true)]
 public class HealthController(NpgsqlDataSource databaseConnectionProvider) : ControllerBase
 {
     [HttpGet]

src/Altinn.Broker.API/Controllers/LegacyFileController.cs

@@ -27,6 +27,7 @@ namespace Altinn.Broker.Controllers;
 [Route("broker/api/v1/legacy/file")]
 [Authorize(AuthenticationSchemes = AuthorizationConstants.Legacy)]
 [Authorize(Policy = AuthorizationConstants.Legacy)]
+[ApiExplorerSettings(IgnoreApi = true)]
 public class LegacyFileController(ILogger<LegacyFileController> logger) : Controller
 {
 

src/Altinn.Broker.API/Controllers/MalwareScanResultsController.cs

@@ -17,6 +17,7 @@ namespace Altinn.Broker.Webhooks.Controllers;
 
 [ApiController]
 [Route("broker/api/v1/webhooks/malwarescanresults")]
+[ApiExplorerSettings(IgnoreApi = true)]
 public class MalwareScanResultsController(IIdempotencyEventRepository idempotencyEventRepository, ILogger<MalwareScanResultsController> logger) : Controller
 {
     [HttpPost]

src/Altinn.Broker.API/Controllers/ResourceController.cs

@@ -15,7 +15,21 @@ namespace Altinn.Broker.Controllers;
 [Authorize(Policy = AuthorizationConstants.ServiceOwner)]
 public class ResourceController : Controller
 {
+    /// <summary>
+    /// Configures a resource with settings to be used within the broker service.
+    /// </summary>
+    /// <remarks>
+    /// Scopes: <br/> 
+    /// - altinn:serviceowner <br/>
+    /// </remarks>
+    /// <returns></returns>
     [HttpPut]
+    [Produces("application/json")]
+    [Consumes("application/json")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
     [Route("{resourceId}")]
     public async Task<ActionResult> ConfigureResource(string resourceId, [FromBody] ResourceExt resourceExt, [FromServices] ConfigureResourceHandler handler, CancellationToken cancellationToken)
     {

src/Altinn.Broker.API/Controllers/ServiceOwnerController.cs

@@ -18,7 +18,17 @@ namespace Altinn.Broker.Controllers;
 [Authorize(Policy = AuthorizationConstants.ServiceOwner)]
 public class ServiceOwnerController(IServiceOwnerRepository serviceOwnerRepository, IHostEnvironment hostEnvironment, IResourceManager resourceManager) : Controller
 {
+    /// <summary>
+    /// Initializes the service owner for the calling organization within the brokerservice.
+    /// </summary>
+    /// <remarks>
+    /// Scopes: <br/>
+    /// - altinn:serviceowner <br/>
+    /// </remarks>
     [HttpPost]
+    [Consumes("application/json")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status409Conflict)]
     public async Task<ActionResult> InitializeServiceOwner([FromBody] ServiceOwnerInitializeExt serviceOwnerInitializeExt, CancellationToken cancellationToken)
     {
         var existingServiceOwner = await serviceOwnerRepository.GetServiceOwner(HttpContext.User.GetCallerOrganizationId().WithPrefix());
@@ -33,8 +43,17 @@ public async Task<ActionResult> InitializeServiceOwner([FromBody] ServiceOwnerIn
         return Ok();
     }
 
+    /// <summary>
+    /// Gets the service owner for the calling organization within the brokerservice.
+    /// </summary>
+    /// <remarks>
+    /// Scopes: <br/>
+    /// - altinn:serviceowner <br/>
+    /// </remarks>
     [HttpGet]
     [Produces("application/json")]
+    [ProducesResponseType(typeof(ServiceOwnerOverviewExt), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<ActionResult<ServiceOwnerOverviewExt>> GetServiceOwner(CancellationToken cancellationToken)
     {
         var serviceOwner = await serviceOwnerRepository.GetServiceOwner(HttpContext.User.GetCallerOrganizationId().WithPrefix());
@@ -49,7 +68,7 @@ public async Task<ActionResult<ServiceOwnerOverviewExt>> GetServiceOwner(Cancell
             var deploymentStatus = await resourceManager.GetDeploymentStatus(storageProvider, cancellationToken);
             deploymentStatuses.Add(storageProvider, deploymentStatus);
         }
-        
+
         return new ServiceOwnerOverviewExt()
         {
             Name = serviceOwner.Name,

src/Altinn.Broker.API/Models/FileTransferInitializeAndUploadExt.cs

@@ -1,8 +1,18 @@
 namespace Altinn.Broker.Models;
 
+
+/// <summary>
+/// A model representing the initialization and upload of a file transfer.
+/// </summary>
 public class FileTransferInitializeAndUploadExt
 {
+    /// <summary>
+    /// The metadata for the file transfer.
+    /// </summary>
     public required FileTransferInitalizeExt Metadata { get; set; }
 
+    /// <summary>
+    /// The file to be uploaded.
+    /// </summary>
     public required IFormFile FileTransfer { get; set; }
 }

src/Altinn.Broker.API/Models/FileTransferInitializeExt.cs

@@ -7,7 +7,7 @@
 namespace Altinn.Broker.Models;
 
 /// <summary>
-/// API input model for file initialization.
+/// A model containing the metadata for a file transfer.
 /// </summary>
 public class FileTransferInitalizeExt
 {
@@ -50,7 +50,7 @@ public class FileTransferInitalizeExt
     [Required]
     [MinLength(1, ErrorMessage = "One or more recipients are required")]
     public List<string> Recipients { get; set; } = new List<string>();
-  
+
     /// <summary>
     /// User-defined properties related to the file
     /// </summary>
@@ -106,7 +106,7 @@ public PropertyListAttribute()
 
     protected override ValidationResult IsValid(object value, ValidationContext validationContext)
     {
-        if(value == null) 
+        if (value == null)
         {
             return ValidationResult.Success;
         }

src/Altinn.Broker.API/Models/FileTransferInitializeResponseExt.cs

@@ -1,6 +1,12 @@
 namespace Altinn.Broker.API.Models;
 
+/// <summary>
+/// Represents the response from initializing a file transfer.
+/// </summary>
 public class FileTransferInitializeResponseExt
 {
+    /// <summary>
+    /// The ID of the file transfer.
+    /// </summary>
     public Guid FileTransferId { get; set; }
 }

src/Altinn.Broker.API/Models/FileTransferOverviewExt.cs

@@ -5,7 +5,7 @@
 namespace Altinn.Broker.Models;
 
 /// <summary>
-/// Overview of a broker file
+/// Overview of a broker file transfer
 /// </summary>
 public class FileTransferOverviewExt
 {

src/Altinn.Broker.API/Models/FileTransferStatusDetailsExt.cs

@@ -1,9 +1,18 @@
 using Altinn.Broker.Models;
 
 namespace Altinn.Broker.Core.Models;
-
+/// <summary>
+/// Overview of a broker file transfer which also includes the status history of the file transfer.|
+/// </summary>
 public class FileTransferStatusDetailsExt : FileTransferOverviewExt
 {
+    /// <summary>
+    /// The status history of the file transfer.
+    /// </summary>
     public List<FileTransferStatusEventExt> FileTransferStatusHistory { get; set; } = new List<FileTransferStatusEventExt>();
+
+    /// <summary>
+    /// The status history of the file transfer for each recipient.
+    /// </summary>
     public List<RecipientFileTransferStatusEventExt> RecipientFileTransferStatusHistory { get; set; } = new List<RecipientFileTransferStatusEventExt>();
 }

src/Altinn.Broker.API/Models/FileTransferStatusEventExt.cs

@@ -2,9 +2,23 @@
 
 namespace Altinn.Broker.Core.Models;
 
+/// <summary>
+/// Represents the status of a file transfer.
+/// </summary>
 public class FileTransferStatusEventExt
 {
+    /// <summary>
+    /// The status code of the file transfer.
+    /// </summary>
     public FileTransferStatusExt FileTransferStatus { get; set; }
+
+    /// <summary>
+    /// The status text of the file transfer.
+    /// </summary>
     public string FileTransferStatusText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The date and time when the status of the file transfer was last changed.
+    /// </summary>
     public DateTimeOffset FileTransferStatusChanged { get; set; }
 }

src/Altinn.Broker.API/Models/FileTransferUploadResponseExt.cs

@@ -1,6 +1,12 @@
 namespace Altinn.Broker.API.Models;
 
+/// <summary>
+/// Represents the response from uploading a file transfer.
+/// </summary>
 public class FileTransferUploadResponseExt
 {
+    /// <summary>
+    /// The ID of the file transfer.
+    /// </summary>
     public Guid FileTransferId { get; set; }
 }