chore: Update swagger summaries, add scopes, global description

src/Digdir.Domain.Dialogporten.Application/Common/Extensions/FluentValidation/FluentValidationUuiDv7Extensions.cs

@@ -21,7 +21,7 @@ public override bool IsValid(ValidationContext<T> context, Guid? value)
     public override string Name { get; } = "Uuid7Validator";
 
     protected override string GetDefaultMessageTemplate(string errorCode) =>
-        "Invalid {PropertyName}. Expected big endian UUIDv7 format. Got '{PropertyValue}'. See [link TBD].";
+        "Invalid {PropertyName}. Expected big endian UUIDv7 format. Got '{PropertyValue}'.";
 }
 
 internal sealed class IsValidUuidV7TimestampValidator<T> : PropertyValidator<T, Guid?>
@@ -46,5 +46,5 @@ public override bool IsValid(ValidationContext<T> context, Guid? value)
     public override string Name { get; } = "Uuid7TimestampValidator";
 
     protected override string GetDefaultMessageTemplate(string errorCode)
-        => "Invalid {PropertyName}. Expected the unix timestamp portion of the UUIDv7 to be in the past. Extrapolated '{date}' from '{PropertyValue}'. See [link TBD].";
+        => "Invalid {PropertyName}. Expected the unix timestamp portion of the UUIDv7 to be in the past. Extrapolated '{date}' from '{PropertyValue}'.";
 }

src/Digdir.Domain.Dialogporten.WebApi/Common/Constants.cs

@@ -10,6 +10,7 @@ internal static class Constants
 
     internal static class SwaggerSummary
     {
+        internal const string GlobalDescription = "Dialogporten API description for both enduser and serviceowner users, as well as open metadata information for public key material.<br><br>All operations* described within this document require authentication and authorization. Read more at <a href=\"https://docs.altinn.studio/dialogporten/user-guides/authenticating/\">https://docs.altinn.studio/dialogporten/user-guides/authenticating/</a><br><br><strong>All GET operations* and POST operations may return or contain, respectively, personal identifiable information (national identity numbers and names).</strong><br><br>For more information about this product, see <a href=\"https://docs.altinn.studio/dialogporten\">https://docs.altinn.studio/dialogporten</a><br><br><em>* Except the metadata APIs";
         internal const string ReturnedResult = "Successfully returned the dialog {0}.";
         internal const string Created = "The UUID of the created dialog {0}. A relative URL to the newly created activity is set in the \"Location\" header.";
         internal const string Deleted = "The dialog {0} was deleted successfully.";

src/Digdir.Domain.Dialogporten.WebApi/Common/Json/SecurityRequirementsOperationProcessor.cs

@@ -0,0 +1,42 @@
+using Digdir.Domain.Dialogporten.Application.Common.Authorization;
+using Digdir.Domain.Dialogporten.WebApi.Endpoints.V1.EndUser;
+using Digdir.Domain.Dialogporten.WebApi.Endpoints.V1.ServiceOwner;
+using NSwag;
+using NSwag.Generation.Processors;
+using NSwag.Generation.Processors.Contexts;
+
+namespace Digdir.Domain.Dialogporten.WebApi.Common.Json;
+
+public sealed class SecurityRequirementsOperationProcessor : IOperationProcessor
+{
+    private const string JwtBearerAuth = "JWTBearerAuth";
+    private const string ServiceOwnerSearchPath = "/api/v1/serviceowner/dialogs";
+
+    public bool Process(OperationProcessorContext context)
+    {
+        var securityRequirement = context.OperationDescription.Operation.Security?.FirstOrDefault();
+        if (securityRequirement == null || !securityRequirement.TryGetValue(JwtBearerAuth, out var value))
+        {
+            return true;
+        }
+
+        securityRequirement[JwtBearerAuth] =
+            context.OperationDescription.Operation.Tags.FirstOrDefault() switch
+            {
+                var tag when string.Equals(tag, ServiceOwnerGroup.RoutePrefix, StringComparison.OrdinalIgnoreCase)
+                    => IsServiceOwnerSearchEndpoint(context.OperationDescription)
+                        ? new[] { AuthorizationScope.ServiceProvider, AuthorizationScope.ServiceProviderSearch }
+                        : new[] { AuthorizationScope.ServiceProvider },
+
+                var tag when string.Equals(tag, EndUserGroup.RoutePrefix, StringComparison.OrdinalIgnoreCase)
+                    => new[] { AuthorizationScope.EndUser },
+
+                _ => value
+            };
+
+        return true;
+    }
+
+    private static bool IsServiceOwnerSearchEndpoint(OpenApiOperationDescription description)
+        => description is { Path: ServiceOwnerSearchPath, Method: OpenApiOperationMethod.Get };
+}

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/EndUser/DialogActivities/Get/GetDialogActivityEndpointSummary.cs

@@ -10,7 +10,7 @@ public GetDialogActivityEndpointSummary()
     {
         Summary = "Gets a single dialog activity";
         Description = """
-                      Gets a single activity belonging to a dialog. For more information see the documentation (link TBD).
+                      Gets a single activity belonging to a dialog.
                       """;
         Responses[StatusCodes.Status200OK] = Constants.SwaggerSummary.ReturnedResult.FormatInvariant("activity");
         Responses[StatusCodes.Status401Unauthorized] = Constants.SwaggerSummary.EndUserAuthenticationFailure;

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/EndUser/DialogSeenLogs/Get/GetDialogSeenLogEndpointSummary.cs

@@ -10,7 +10,7 @@ public GetDialogSeenLogEndpointSummary()
     {
         Summary = "Gets a single dialog seen log record";
         Description = """
-                      Gets a single dialog seen log record. For more information see the documentation (link TBD).
+                      Gets a single dialog seen log record.
                       """;
 
         Responses[StatusCodes.Status200OK] = Constants.SwaggerSummary.ReturnedResult.FormatInvariant("seen log record");

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/EndUser/DialogSeenLogs/Search/SearchDialogSeenLogEndpointSummary.cs

@@ -11,7 +11,7 @@ public SearchDialogSeenLogEndpointSummary()
         const string summary = "Gets all seen log records for a dialog";
         Summary = summary;
         Description = $"""
-                      {summary}. For more information see the documentation (link TBD).
+                      {summary}.
                       """;
 
         Responses[StatusCodes.Status200OK] = Constants.SwaggerSummary.ReturnedResult.FormatInvariant("seen log records");

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/EndUser/DialogTransmissions/Get/GetDialogTransmissionEndpointSummary.cs

@@ -11,7 +11,7 @@ public GetDialogTransmissionEndpointSummary()
     {
         Summary = "Gets a single dialog transmission";
         Description = """
-                      Gets a single transmission belonging to a dialog. For more information see the documentation (link TBD).
+                      Gets a single transmission belonging to a dialog.
                       """;
         Responses[StatusCodes.Status200OK] = Constants.SwaggerSummary.ReturnedResult.FormatInvariant("transmission");
         Responses[StatusCodes.Status401Unauthorized] = Constants.SwaggerSummary.EndUserAuthenticationFailure.FormatInvariant(AuthorizationScope.EndUser);

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/EndUser/Dialogs/Get/GetDialogEndpointSummary.cs

@@ -10,7 +10,7 @@ public GetDialogEndpointSummary()
     {
         Summary = "Gets a single dialog";
         Description = """
-                      Gets a single dialog aggregate. For more information see the documentation (link TBD).
+                      Gets a single dialog aggregate. 
                       """;
 
         Responses[StatusCodes.Status200OK] =

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/EndUser/Dialogs/Search/SearchDialogEndpointSummary.cs

@@ -12,7 +12,7 @@ public SearchDialogEndpointSummary()
     {
         Summary = "Gets a list of dialogs";
         Description = """
-                      Performs a search for dialogs, returning a paginated list of dialogs. For more information see the documentation (link TBD).
+                      Performs a search for dialogs, returning a paginated list of dialogs. 
 
                       * All date parameters must contain explicit time zone. Example: 2023-10-27T10:00:00Z or 2023-10-27T10:00:00+01:00
                       * See "continuationToken" in the response for how to get the next page of results.

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/EndUser/Parties/Get/GetPartiesEndpointSummary.cs

@@ -8,7 +8,7 @@ public GetPartiesEndpointSummary()
     {
         Summary = "Gets the list of authorized parties for the end user";
         Description = """
-                      Gets the list of authorized parties for the end user. For more information see the documentation (link TBD).
+                      Gets the list of authorized parties for the end user.
                       """;
 
         Responses[StatusCodes.Status200OK] = "The list of authorized parties for the end user";

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/DialogActivities/Create/CreateDialogActivityEndpointSummary.cs

@@ -12,7 +12,7 @@ public CreateDialogActivityEndpointSummary()
     {
         Summary = "Adds a activity to a dialogs activity history";
         Description = $"""
-                       The activity is created with the given configuration. For more information see the documentation (link TBD).
+                       The activity is created with the given configuration.
 
                        {Constants.SwaggerSummary.OptimisticConcurrencyNote}
                        """;

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/DialogActivities/Get/GetDialogActivitySwaggerConfig.cs

@@ -11,7 +11,7 @@ public GetDialogActivityEndpointSummary()
     {
         Summary = "Gets a single dialog activity";
         Description = """
-                      Gets a single activity belonging to a dialog. For more information see the documentation (link TBD).
+                      Gets a single activity belonging to a dialog.
                       """;
         Responses[StatusCodes.Status200OK] = Constants.SwaggerSummary.ReturnedResult.FormatInvariant("activity");
         Responses[StatusCodes.Status401Unauthorized] = Constants.SwaggerSummary.ServiceOwnerAuthenticationFailure.FormatInvariant(AuthorizationScope.ServiceProvider);

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/DialogSeenLogs/Get/GetDialogSeenLogEndpointSummary.cs

@@ -10,7 +10,7 @@ public GetDialogSeenLogEndpointSummary()
     {
         Summary = "Gets a single dialog seen log record";
         Description = """
-                      Gets a single dialog seen log record. For more information see the documentation (link TBD).
+                      Gets a single dialog seen log record.
                       """;
 
         Responses[StatusCodes.Status200OK] = Constants.SwaggerSummary.ReturnedResult.FormatInvariant("seen log record");

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/DialogSeenLogs/Search/SearchDialogSeenLogEndpointSummary.cs

@@ -11,7 +11,7 @@ public SearchDialogSeenLogEndpointSummary()
         const string summary = "Gets all seen log records for a dialog";
         Summary = summary;
         Description = $"""
-                      {summary}. For more information see the documentation (link TBD).
+                      {summary}.
                       """;
 
         Responses[StatusCodes.Status200OK] = Constants.SwaggerSummary.ReturnedResult.FormatInvariant("seen log records");

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/DialogTransmissions/Create/CreateDialogTransmissionEndpointSummary.cs

@@ -12,7 +12,7 @@ public CreateDialogTransmissionEndpointSummary()
     {
         Summary = "Adds a transmission to a dialog";
         Description = $"""
-                       The transmission is created with the given configuration. For more information see the documentation (link TBD).
+                       The transmission is created with the given configuration.
 
                        {Constants.SwaggerSummary.OptimisticConcurrencyNote}
                        """;

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/DialogTransmissions/Get/GetDialogTransmissionEndpointSummary.cs

@@ -11,7 +11,7 @@ public GetDialogTransmissionEndpointSummary()
     {
         Summary = "Gets a single dialog transmission";
         Description = """
-                      Gets a single transmission belonging to a dialog. For more information see the documentation (link TBD).
+                      Gets a single transmission belonging to a dialog.
                       """;
         Responses[StatusCodes.Status200OK] = Constants.SwaggerSummary.ReturnedResult.FormatInvariant("transmission");
         Responses[StatusCodes.Status401Unauthorized] = Constants.SwaggerSummary.ServiceOwnerAuthenticationFailure.FormatInvariant(AuthorizationScope.ServiceProvider);

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/Dialogs/Create/CreateDialogEndpointSummary.cs

@@ -12,7 +12,7 @@ public CreateDialogEndpointSummary()
     {
         Summary = "Creates a new dialog";
         Description = """
-                      The dialog is created with the given configuration. For more information see the documentation (link TBD).
+                      The dialog is created with the given configuration.
 
                       For detailed information on validation rules, see [the source for CreateDialogCommandValidator](https://github.com/altinn/dialogporten/blob/main/src/Digdir.Domain.Dialogporten.Application/Features/V1/ServiceOwner/Dialogs/Commands/Create/CreateDialogCommandValidator.cs)
                       """;

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/Dialogs/Delete/DeleteDialogEndpointSummary.cs

@@ -12,7 +12,7 @@ public DeleteDialogEndpointSummary()
     {
         Summary = "Deletes a dialog";
         Description = """
-                      Deletes a given dialog (soft delete). For more information see the documentation (link TBD).
+                      Deletes a given dialog (soft delete).
 
                       Note that the dialog will still be available on the single details endpoint, but will have a deleted status. It will not appear on the list endpoint for either service owners nor end users.
                       If end users attempt to access the dialog via the details endpoint, they will get a 410 Gone response.

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/Dialogs/Get/GetDialogEndpointSummary.cs

@@ -11,7 +11,7 @@ public GetDialogEndpointSummary()
     {
         Summary = "Gets a single dialog";
         Description = """
-                      Gets a single dialog aggregate. For more information see the documentation (link TBD).
+                      Gets a single dialog aggregate.
 
                       Note that this operation may return deleted dialogs (see the field `DeletedAt`).
                       """;

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/Dialogs/Purge/PurgeDialogEndpointSummary.cs

@@ -11,7 +11,7 @@ public PurgeDialogEndpointSummary()
     {
         Summary = "Permanently deletes a dialog";
         Description = """
-                      Deletes a given dialog (hard delete). For more information see the documentation (link TBD).
+                      Deletes a given dialog (hard delete).
 
                       Optimistic concurrency control is implemented using the If-Match header. Supply the Revision value from the GetDialog endpoint to ensure that the dialog is not deleted by another request in the meantime.
                       """;

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/Dialogs/Restore/RestoreDialogEndpointSummary.cs

@@ -10,7 +10,7 @@ public RestoreDialogEndpointSummary()
     {
         Summary = "Restore a dialog";
         Description = """
-                      Restore a dialog. For more information see the documentation (link TBD). 
+                      Restore a dialog. 
                       """;
 
         Responses[StatusCodes.Status204NoContent] = Constants.SwaggerSummary.Restored.FormatInvariant("aggregate");

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/Dialogs/Search/ListDialogEndpointSummary.cs

@@ -13,7 +13,7 @@ public ListDialogEndpointSummary()
     {
         Summary = "Gets a list of dialogs";
         Description = """
-                      Performs a search for dialogs, returning a paginated list of dialogs. For more information see the documentation (link TBD).
+                      Performs a search for dialogs, returning a paginated list of dialogs.
 
                       * All date parameters must contain explicit time zone. Example: 2023-10-27T10:00:00Z or 2023-10-27T10:00:00+01:00
                       * See "continuationToken" in the response for how to get the next page of results.

src/Digdir.Domain.Dialogporten.WebApi/Endpoints/V1/ServiceOwner/Dialogs/Update/UpdateDialogEndpointSummary.cs

@@ -12,7 +12,7 @@ public UpdateDialogEndpointSummary()
     {
         Summary = "Replaces a dialog";
         Description = $"""
-                       Replaces a given dialog with the supplied model. For more information see the documentation (link TBD).
+                       Replaces a given dialog with the supplied model.
 
                        {Constants.SwaggerSummary.OptimisticConcurrencyNote}
                        """;

src/Digdir.Domain.Dialogporten.WebApi/Program.cs

@@ -136,6 +136,7 @@ static void BuildAndRun(string[] args)
                     document.RemoveSystemStringHeaderTitles();
                 };
                 s.Title = "Dialogporten";
+                s.Description = Constants.SwaggerSummary.GlobalDescription;
                 s.DocumentName = "v1";
                 s.Version = "v1";
 
@@ -150,6 +151,9 @@ static void BuildAndRun(string[] args)
 
                 // Adding ResponseHeaders for PATCH MVC controller
                 s.OperationProcessors.Add(new ProducesResponseHeaderOperationProcessor());
+
+                // Adding required scopes to security definitions
+                s.OperationProcessors.Add(new SecurityRequirementsOperationProcessor());
             };
         })
         .AddControllers(options => options.InputFormatters.Insert(0, JsonPatchInputFormatter.Get()))