Improve API docs (#1054)

* chore: set correct status code and responses

* chore: enable Swagger UI

* Revert "chore: enable Swagger UI"

This reverts commit 4c52448.

---------

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Applications/AdminApi/src/AdminApi/Controllers/ClientsController.cs

@@ -37,7 +37,7 @@ public async Task<IActionResult> GetAllClients(CancellationToken cancellationTok
     }
 
     [HttpGet("{id}")]
-    [ProducesResponseType(typeof(ClientDTO), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<ClientDTO>), StatusCodes.Status200OK)]
     [ProducesError(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetClient([FromRoute] string id, CancellationToken cancellationToken)
     {

Applications/AdminApi/src/AdminApi/Controllers/IdentitiesController.cs

@@ -31,7 +31,7 @@ public IdentitiesController(IMediator mediator) : base(mediator)
     }
 
     [HttpPost("{identityAddress}/Quotas")]
-    [ProducesResponseType(typeof(IndividualQuotaDTO), StatusCodes.Status201Created)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<IndividualQuotaDTO>), StatusCodes.Status201Created)]
     [ProducesError(StatusCodes.Status404NotFound)]
     [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<CreatedResult> CreateIndividualQuota([FromRoute] string identityAddress, [FromBody] CreateQuotaForIdentityRequest request, CancellationToken cancellationToken)
@@ -51,7 +51,7 @@ public async Task<IActionResult> DeleteIndividualQuota([FromRoute] string identi
     }
 
     [HttpGet("{address}")]
-    [ProducesResponseType(typeof(GetIdentityResponse), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<GetIdentityResponse>), StatusCodes.Status200OK)]
     [ProducesError(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetIdentityByAddress([FromRoute] string address, CancellationToken cancellationToken)
     {
@@ -119,7 +119,7 @@ public async Task<IActionResult> StartDeletionProcess([FromRoute] string address
     }
 
     [HttpGet("{identityAddress}/DeletionProcesses")]
-    [ProducesResponseType(typeof(GetDeletionProcessesAsSupportResponse), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<GetDeletionProcessesAsSupportResponse>), StatusCodes.Status200OK)]
     [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<IActionResult> GetDeletionProcessesAsSupport([FromRoute] string identityAddress, CancellationToken cancellationToken)
     {
@@ -128,7 +128,7 @@ public async Task<IActionResult> GetDeletionProcessesAsSupport([FromRoute] strin
     }
 
     [HttpGet("{identityAddress}/DeletionProcesses/AuditLogs")]
-    [ProducesResponseType(typeof(GetDeletionProcessesAuditLogsResponse), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<GetDeletionProcessesAuditLogsResponse>), StatusCodes.Status200OK)]
     [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<IActionResult> GetDeletionProcessesAuditLogs([FromRoute] string identityAddress, CancellationToken cancellationToken)
     {
@@ -146,7 +146,7 @@ public async Task<IActionResult> CancelDeletionProcessAsSupport([FromRoute] stri
     }
 
     [HttpGet("{identityAddress}/DeletionProcesses/{deletionProcessId}")]
-    [ProducesResponseType(typeof(IdentityDeletionProcessDetailsDTO), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<IdentityDeletionProcessDetailsDTO>), StatusCodes.Status200OK)]
     [ProducesError(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetDeletionProcessAsSupport([FromRoute] string identityAddress, [FromRoute] string deletionProcessId, CancellationToken cancellationToken)
     {

Applications/AdminApi/src/AdminApi/Controllers/TiersController.cs

@@ -37,7 +37,7 @@ public async Task<IActionResult> GetTiers(CancellationToken cancellationToken)
     }
 
     [HttpGet("{tierId}")]
-    [ProducesResponseType(typeof(TierDetailsDTO), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<TierDetailsDTO>), StatusCodes.Status200OK)]
     [ProducesError(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetTierByIdAsync([FromRoute] string tierId, CancellationToken cancellationToken)
     {
@@ -46,7 +46,7 @@ public async Task<IActionResult> GetTierByIdAsync([FromRoute] string tierId, Can
     }
 
     [HttpPost]
-    [ProducesResponseType(typeof(CreateTierResponse), StatusCodes.Status201Created)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<CreateTierResponse>), StatusCodes.Status201Created)]
     [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<CreatedResult> PostTiers([FromBody] CreateTierCommand command, CancellationToken cancellationToken)
     {
@@ -66,7 +66,7 @@ public async Task<IActionResult> DeleteTier([FromRoute] string tierId, Cancellat
     }
 
     [HttpPost("{tierId}/Quotas")]
-    [ProducesResponseType(typeof(TierQuotaDefinitionDTO), StatusCodes.Status201Created)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<TierQuotaDefinitionDTO>), StatusCodes.Status201Created)]
     [ProducesError(StatusCodes.Status404NotFound)]
     [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<CreatedResult> CreateTierQuota([FromRoute] string tierId, [FromBody] CreateQuotaForTierRequest request, CancellationToken cancellationToken)

Applications/AdminApi/src/AdminApi/Controllers/TokensController.cs

@@ -1,4 +1,5 @@
-using Backbone.BuildingBlocks.API.Mvc;
+using Backbone.BuildingBlocks.API;
+using Backbone.BuildingBlocks.API.Mvc;
 using Backbone.BuildingBlocks.Application.Abstractions.Exceptions;
 using Backbone.BuildingBlocks.Application.Pagination;
 using Backbone.Modules.Tokens.Application;
@@ -17,7 +18,7 @@ namespace Backbone.AdminApi.Controllers;
 public class TokensController(IMediator mediator, IOptions<ApplicationOptions> options) : ApiControllerBase(mediator)
 {
     [HttpGet]
-    [ProducesResponseType(typeof(List<TokenDTO>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<List<TokenDTO>>), StatusCodes.Status200OK)]
     public async Task<IActionResult> ListTokensByIdentity([FromQuery] PaginationFilter paginationFilter, [FromQuery] string createdBy, CancellationToken cancellationToken)
     {
         if (paginationFilter.PageSize != null)

Applications/ConsumerApi/src/Controllers/AuthorizationController.cs

@@ -33,13 +33,17 @@ public AuthorizationController(
         _userManager = userManager;
     }
 
-    [HttpPost("~/connect/token"), IgnoreAntiforgeryToken, Produces("application/json"),
-     Consumes("application/x-www-form-urlencoded")]
+    [HttpPost("~/connect/token")]
+    [IgnoreAntiforgeryToken]
+    [Produces("application/json")]
+    [Consumes("application/x-www-form-urlencoded")]
     [AllowAnonymous]
+    [ApiExplorerSettings(IgnoreApi = true)]
     public async Task<IActionResult> Exchange()
     {
         var request = HttpContext.GetOpenIddictServerRequest() ?? throw new OperationFailedException(
             ApplicationErrors.Authentication.InvalidOAuthRequest("no request was found"));
+
         if (!request.IsPasswordGrantType())
             throw new OperationFailedException(
                 ApplicationErrors.Authentication.InvalidOAuthRequest("the specified grant type is not implemented"));

Applications/ConsumerApi/src/Program.cs

@@ -201,8 +201,6 @@ static void Configure(WebApplication app)
             .AddCustomHeader("X-Frame-Options", "Deny")
     );
 
-    var configuration = app.Services.GetRequiredService<IOptions<BackboneConfiguration>>().Value;
-
     if (app.Environment.IsDevelopment())
         IdentityModelEventSource.ShowPII = true;
 

Modules/Announcements/src/Announcements.ConsumerApi/Controllers/AnnouncementsController.cs

@@ -1,7 +1,10 @@
-using Backbone.BuildingBlocks.API.Mvc;
+using Backbone.BuildingBlocks.API;
+using Backbone.BuildingBlocks.API.Mvc;
+using Backbone.BuildingBlocks.API.Mvc.ControllerAttributes;
 using Backbone.Modules.Announcements.Application.Announcements.Queries.GetAllAnnouncementsInLanguage;
 using MediatR;
 using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 
 namespace Backbone.Modules.Announcements.ConsumerApi.Controllers;
@@ -15,6 +18,8 @@ public AnnouncementsController(IMediator mediator) : base(mediator)
     }
 
     [HttpGet]
+    [ProducesResponseType<HttpResponseEnvelopeResult<GetAllAnnouncementsInLanguageResponse>>(StatusCodes.Status200OK)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<IActionResult> GetAllAnnouncements([FromQuery] string language)
     {
         var announcements = await _mediator.Send(new GetAllAnnouncementsInLanguageQuery { Language = language });

Modules/Challenges/src/Challenges.ConsumerApi/Controllers/ChallengesController.cs

@@ -4,7 +4,6 @@
 using Backbone.Modules.Challenges.Application.Challenges.Commands.CreateChallenge;
 using Backbone.Modules.Challenges.Application.Challenges.DTOs;
 using Backbone.Modules.Challenges.Application.Challenges.Queries.GetChallengeById;
-using Backbone.Modules.Challenges.Domain.Ids;
 using MediatR;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Http;
@@ -32,8 +31,9 @@ public async Task<IActionResult> Create(CancellationToken cancellationToken)
 
     [HttpGet("{id}")]
     [ProducesResponseType(typeof(HttpResponseEnvelopeResult<ChallengeDTO>), StatusCodes.Status200OK)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     [ProducesError(StatusCodes.Status404NotFound)]
-    public async Task<IActionResult> GetById([FromRoute] ChallengeId id, CancellationToken cancellationToken)
+    public async Task<IActionResult> GetById([FromRoute] string id, CancellationToken cancellationToken)
     {
         var @event = await _mediator.Send(new GetChallengeByIdQuery { Id = id }, cancellationToken);
         return Ok(@event);

Modules/Devices/src/Devices.ConsumerApi/Controllers/DevicesController.cs

@@ -3,7 +3,6 @@
 using Backbone.BuildingBlocks.API.Mvc.ControllerAttributes;
 using Backbone.BuildingBlocks.Application.Abstractions.Exceptions;
 using Backbone.BuildingBlocks.Application.Pagination;
-using Backbone.DevelopmentKit.Identity.ValueObjects;
 using Backbone.Modules.Devices.Application;
 using Backbone.Modules.Devices.Application.Devices.Commands.ChangePassword;
 using Backbone.Modules.Devices.Application.Devices.Commands.DeleteDevice;
@@ -74,6 +73,7 @@ public async Task<IActionResult> ChangePassword(ChangePasswordCommand request, C
 
     [HttpGet]
     [ProducesResponseType(typeof(PagedHttpResponseEnvelope<ListDevicesResponse>), StatusCodes.Status200OK)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<IActionResult> ListDevices([FromQuery] PaginationFilter paginationFilter, [FromQuery] IEnumerable<string> ids, CancellationToken cancellationToken)
     {
         paginationFilter.PageSize ??= _options.Pagination.DefaultPageSize;
@@ -88,18 +88,17 @@ public async Task<IActionResult> ListDevices([FromQuery] PaginationFilter pagina
 
     [HttpGet("Self")]
     [ProducesResponseType(typeof(HttpResponseEnvelopeResult<DeviceDTO>), StatusCodes.Status200OK)]
-    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetActiveDevice()
     {
         var response = await _mediator.Send(new GetActiveDeviceQuery());
         return Ok(response);
     }
 
     [HttpDelete("{id}")]
-    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
     [ProducesError(StatusCodes.Status400BadRequest)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
-    public async Task<IActionResult> DeleteDevice([FromRoute] DeviceId id, CancellationToken cancellationToken)
+    public async Task<IActionResult> DeleteDevice([FromRoute] string id, CancellationToken cancellationToken)
     {
         await _mediator.Send(new DeleteDeviceCommand { DeviceId = id }, cancellationToken);
         return NoContent();

Modules/Devices/src/Devices.ConsumerApi/Controllers/IdentitiesController.cs

@@ -19,7 +19,6 @@
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
-using Microsoft.Extensions.Logging;
 using OpenIddict.Core;
 using OpenIddict.Validation.AspNetCore;
 
@@ -30,20 +29,18 @@ namespace Backbone.Modules.Devices.ConsumerApi.Controllers;
 public class IdentitiesController : ApiControllerBase
 {
     private readonly OpenIddictApplicationManager<CustomOpenIddictEntityFrameworkCoreApplication> _applicationManager;
-    private readonly ILogger<IdentitiesController> _logger;
 
     public IdentitiesController(
         IMediator mediator,
-        OpenIddictApplicationManager<CustomOpenIddictEntityFrameworkCoreApplication> applicationManager,
-        ILogger<IdentitiesController> logger) : base(mediator)
+        OpenIddictApplicationManager<CustomOpenIddictEntityFrameworkCoreApplication> applicationManager) : base(mediator)
     {
         _applicationManager = applicationManager;
-        _logger = logger;
     }
 
     [HttpPost]
     [ProducesResponseType(typeof(HttpResponseEnvelopeResult<CreateIdentityResponse>), StatusCodes.Status201Created)]
     [ProducesError(StatusCodes.Status400BadRequest)]
+    [ProducesError(StatusCodes.Status404NotFound)]
     [AllowAnonymous]
     public async Task<IActionResult> CreateIdentity(CreateIdentityRequest request, CancellationToken cancellationToken)
     {
@@ -103,6 +100,7 @@ public async Task<IActionResult> RejectDeletionProcess([FromRoute] string id, Ca
 
     [HttpGet("Self/DeletionProcesses/{id}")]
     [ProducesResponseType(typeof(HttpResponseEnvelopeResult<IdentityDeletionProcessOverviewDTO>), StatusCodes.Status200OK)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     [ProducesError(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetDeletionProcess([FromRoute] string id, CancellationToken cancellationToken)
     {
@@ -138,8 +136,8 @@ public async Task<IActionResult> GetOwnIdentity(CancellationToken cancellationTo
 
     [HttpGet("IsDeleted")]
     [AllowAnonymous]
-    [ProducesResponseType(typeof(IsIdentityOfUserDeletedResponse), StatusCodes.Status200OK)]
-    [ProducesError(StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<IsIdentityOfUserDeletedResponse>), StatusCodes.Status200OK)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<IActionResult> IsIdentityOfUserDeleted([FromQuery(Name = "username")] string username, CancellationToken cancellationToken)
     {
         var response = await _mediator.Send(new IsIdentityOfUserDeletedQuery { Username = username }, cancellationToken);

Modules/Devices/src/Devices.ConsumerApi/Controllers/PushNotificationsController.cs

@@ -1,3 +1,4 @@
+using Backbone.BuildingBlocks.API;
 using Backbone.BuildingBlocks.API.Mvc;
 using Backbone.BuildingBlocks.API.Mvc.ControllerAttributes;
 using Backbone.Modules.Devices.Application.PushNotifications.Commands.DeleteDeviceRegistration;
@@ -15,10 +16,12 @@ namespace Backbone.Modules.Devices.ConsumerApi.Controllers;
 [Authorize(OpenIddictValidationAspNetCoreDefaults.AuthenticationScheme)]
 public class PushNotificationsController : ApiControllerBase
 {
-    public PushNotificationsController(IMediator mediator) : base(mediator) { }
+    public PushNotificationsController(IMediator mediator) : base(mediator)
+    {
+    }
 
     [HttpPut]
-    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<UpdateDeviceRegistrationResponse>), StatusCodes.Status200OK)]
     [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<IActionResult> RegisterForPushNotifications(UpdateDeviceRegistrationCommand request, CancellationToken cancellationToken)
     {
@@ -35,6 +38,7 @@ public async Task<IActionResult> UnregisterFromPushNotifications(CancellationTok
     }
 
     [HttpPost("SendTestNotification")]
+    [ApiExplorerSettings(IgnoreApi = true)] // don't show this in the API docs as it's just for internal testing 
     [ProducesResponseType(StatusCodes.Status204NoContent)]
     public async Task<IActionResult> SendTestPushNotification([FromBody] dynamic data, CancellationToken cancellationToken)
     {

Modules/Files/src/Files.ConsumerApi/Controllers/FilesController.cs

@@ -63,8 +63,8 @@ public async Task<IActionResult> UploadFile([FromForm] CreateFileDTO dto, Cancel
     }
 
     [HttpGet("{fileId}")]
-    [Produces(MediaTypeNames.Application.Octet)]
-    [ProducesResponseType(typeof(HttpResponseEnvelopeResult<FileContentResult>), StatusCodes.Status200OK)]
+    [ProducesResponseType<byte[]>(StatusCodes.Status200OK, MediaTypeNames.Application.Octet)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     [ProducesError(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> DownloadFile(string fileId, CancellationToken cancellationToken)
     {
@@ -73,8 +73,9 @@ public async Task<IActionResult> DownloadFile(string fileId, CancellationToken c
     }
 
 
-    [HttpGet("{fileId}/metadata")]
+    [HttpGet("{fileId}/Metadata")]
     [ProducesResponseType(typeof(HttpResponseEnvelopeResult<FileMetadataDTO>), StatusCodes.Status200OK)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     [ProducesError(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetFileMetadata(string fileId, CancellationToken cancellationToken)
     {
@@ -84,6 +85,7 @@ public async Task<IActionResult> GetFileMetadata(string fileId, CancellationToke
 
     [HttpDelete("{fileId}")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     [ProducesError(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> DeleteFile(string fileId, CancellationToken cancellationToken)
     {
@@ -93,6 +95,7 @@ public async Task<IActionResult> DeleteFile(string fileId, CancellationToken can
 
     [HttpGet]
     [ProducesResponseType(typeof(PagedHttpResponseEnvelope<ListFileMetadataResponse>), StatusCodes.Status200OK)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<IActionResult> ListFileMetadata([FromQuery] PaginationFilter paginationFilter,
         [FromQuery] IEnumerable<string> ids, CancellationToken cancellationToken)
     {

Modules/Messages/src/Messages.ConsumerApi/Controllers/MessagesController.cs

@@ -30,6 +30,7 @@ public MessagesController(IMediator mediator, IOptions<ApplicationOptions> optio
 
     [HttpGet]
     [ProducesResponseType(typeof(PagedHttpResponseEnvelope<ListMessagesResponse>), StatusCodes.Status200OK)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     public async Task<IActionResult> ListMessages([FromQuery] PaginationFilter paginationFilter,
         [FromQuery] IEnumerable<string> ids, CancellationToken cancellationToken)
     {
@@ -47,6 +48,7 @@ public async Task<IActionResult> ListMessages([FromQuery] PaginationFilter pagin
 
     [HttpGet("{id}")]
     [ProducesResponseType(typeof(HttpResponseEnvelopeResult<MessageDTO>), StatusCodes.Status200OK)]
+    [ProducesError(StatusCodes.Status400BadRequest)]
     [ProducesError(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetMessage(string id, [FromQuery] bool? noBody, CancellationToken cancellationToken)
     {

Modules/Relationships/src/Relationships.ConsumerApi/Controllers/PublicRelationshipTemplateReferencesController.cs

@@ -9,6 +9,7 @@ namespace Backbone.Modules.Relationships.ConsumerApi.Controllers;
 
 [Route("api/poc/[controller]")]
 [Authorize("OpenIddict.Validation.AspNetCore")]
+[ApiExplorerSettings(IgnoreApi = true)] // don't show this endpoints of this controller in the API docs as it's just a PoC
 public class PublicRelationshipTemplateReferencesController : ApiControllerBase
 {
     private readonly Configuration _options;