Update docstrings and move classes into separate model files (#553)

* minor changes in docstring

* separate classes into dedicated files for ext models

src/Altinn.Correspondence.API/Models/BaseCorrespondenceExt.cs

@@ -10,7 +10,7 @@ namespace Altinn.Correspondence.API.Models
     public class BaseCorrespondenceExt
     {
         /// <summary>
-        /// Gets or sets the Resource Id for the correspondence service.
+        /// The Resource Id associated with the correspondence service.
         /// </summary>
         [JsonPropertyName("resourceId")]
         [StringLength(255, MinimumLength = 1)]
@@ -21,15 +21,15 @@ public class BaseCorrespondenceExt
         /// The Sending organization of the correspondence. 
         /// </summary>
         /// <remarks>
-        /// Organization number in countrycode:organizationnumber format.
+        /// Organization number must be formatted as countrycode:organizationnumber.
         /// </remarks>
         [JsonPropertyName("sender")]
         [OrganizationNumber(ErrorMessage = $"Organization numbers should be on the format '{UrnConstants.OrganizationNumberAttribute}:organizationnumber' or the format countrycode:organizationnumber, for instance 0192:910753614")]
         [Required]
         public required string Sender { get; set; }
 
         /// <summary>
-        /// Used by senders and receivers to identify specific a Correspondence using external identification methods.
+        /// A reference used by senders and receivers to identify a specific Correspondence using external identification methods.
         /// </summary>
         [JsonPropertyName("sendersReference")]
         [StringLength(4096, MinimumLength = 1)]
@@ -56,23 +56,21 @@ public class BaseCorrespondenceExt
         public DateTimeOffset? RequestedPublishTime { get; set; }
 
         /// <summary>
-        /// Gets or sets the date for when Altinn can remove the correspondence from its database.
+        /// When Altinn can remove the correspondence from its database.
         /// </summary>
         [JsonPropertyName("allowSystemDeleteAfter")]
         public DateTimeOffset? AllowSystemDeleteAfter { get; set; }
 
         /// <summary>
-        /// Gets or sets a date and time for when the recipient must reply.
+        /// When the recipient must reply to the correspondence
         /// </summary>
         [JsonPropertyName("dueDateTime")]
         public DateTimeOffset? DueDateTime { get; set; }
 
         /// <summary>
-        /// Gets or sets an list of references Senders can use this field to tell the recipient that the correspondence is related to the referenced item(s)
+        /// A list of references Senders can use to tell the recipient that the correspondence is related to the referenced item(s)
         /// Examples include Altinn App instances, Altinn Broker File Transfers
         /// </summary>
-        /// <remarks>
-        /// </remarks>
         [JsonPropertyName("externalReferences")]
         [ExternalReferences]
         public List<ExternalReferenceExt>? ExternalReferences { get; set; }
@@ -85,13 +83,13 @@ public class BaseCorrespondenceExt
         public Dictionary<string, string> PropertyList { get; set; } = new Dictionary<string, string>();
 
         /// <summary>
-        /// Options for how the recipient can reply to the correspondence
+        /// Options for how the recipient can reply to the Correspondence
         /// </summary>
         [JsonPropertyName("replyOptions")]
         public List<CorrespondenceReplyOptionExt> ReplyOptions { get; set; } = new List<CorrespondenceReplyOptionExt>();
 
         /// <summary>
-        /// Notifications directly related to this Correspondence.
+        /// Notifications related to the Correspondence.
         /// </summary>
         [JsonPropertyName("notification")]
         public InitializeCorrespondenceNotificationExt? Notification { get; set; }

src/Altinn.Correspondence.API/Models/InitializeCorrespondencesExt.cs

@@ -14,7 +14,7 @@ public class InitializeCorrespondencesExt
     public required BaseCorrespondenceExt Correspondence { get; set; }
 
     /// <summary>
-    /// The recipients of the correspondence, either an organisation or an person
+    /// List of recipients for the correspondence, either as organization or national identity number
     /// </summary>
     [JsonPropertyName("recipients")]
     [Required]

src/Altinn.Correspondence.API/Models/InitializeCorrespondencesResponseExt.cs

@@ -1,45 +1,21 @@
 using System.Text.Json.Serialization;
-using Altinn.Correspondence.API.Models.Enums;
 
 namespace Altinn.Correspondence.API.Models;
 
+/// <summary>
+/// Response object for initializing correspondences. Contains information about the created correspondences and their attachments.
+/// </summary>
 public class InitializeCorrespondencesResponseExt
 {
+    /// <summary>
+    /// The initialized correspondences
+    /// </summary>
     [JsonPropertyName("correspondences")]
     public List<InitializedCorrespondencesExt> Correspondences { get; set; }
+
+    /// <summary>
+    /// The IDs of the attachments that were included with the correspondences
+    /// </summary>
     [JsonPropertyName("attachmentIds")]
     public List<Guid> AttachmentIds { get; set; }
 }
-
-
-public class InitializedCorrespondencesExt
-{
-    [JsonPropertyName("correspondenceId")]
-    public Guid CorrespondenceId { get; set; }
-
-    [JsonPropertyName("status")]
-    public CorrespondenceStatusExt Status { get; set; }
-
-    [JsonPropertyName("recipient")]
-    public required string Recipient { get; set; }
-
-    [JsonPropertyName("notifications")]
-    public List<InitializedCorrespondencesNotificationsExt>? Notifications { get; set; }
-}
-public class InitializedCorrespondencesNotificationsExt
-{
-    [JsonPropertyName("orderId")]
-    public Guid? OrderId { get; set; }
-
-    [JsonPropertyName("isReminder")]
-    public bool? IsReminder { get; set; }
-
-    [JsonPropertyName("status")]
-    public InitializedNotificationStatusExt Status { get; set; }
-}
-public enum InitializedNotificationStatusExt
-{
-    Success,
-    MissingContact,
-    Failure,
-}

src/Altinn.Correspondence.API/Models/InitializedCorrespondencesExt.cs

@@ -0,0 +1,34 @@
+
+using System.Text.Json.Serialization;
+using Altinn.Correspondence.API.Models.Enums;
+
+namespace Altinn.Correspondence.API.Models;
+/// <summary>
+/// Represents a correspondence that has been initialized
+/// </summary>
+public class InitializedCorrespondencesExt
+{
+    /// <summary>
+    /// The ID of the correspondence
+    /// </summary>
+    [JsonPropertyName("correspondenceId")]
+    public Guid CorrespondenceId { get; set; }
+
+    /// <summary>
+    /// The status of the correspondence
+    /// </summary>
+    [JsonPropertyName("status")]
+    public CorrespondenceStatusExt Status { get; set; }
+
+    /// <summary>
+    /// The recipient of the correspondence
+    /// </summary>
+    [JsonPropertyName("recipient")]
+    public required string Recipient { get; set; }
+
+    /// <summary>
+    /// Information about the notifications that were created for the correspondence
+    /// </summary>
+    [JsonPropertyName("notifications")]
+    public List<InitializedCorrespondencesNotificationsExt>? Notifications { get; set; }
+}

src/Altinn.Correspondence.API/Models/InitializedCorrespondencesNotificationsExt.cs

@@ -0,0 +1,42 @@
+
+using System.Text.Json.Serialization;
+
+namespace Altinn.Correspondence.API.Models;
+/// <summary>
+/// Information about the notifications that were created for the correspondence
+/// </summary>
+public class InitializedCorrespondencesNotificationsExt
+{
+    /// <summary>
+    /// The order ID of the notification
+    /// </summary>
+    [JsonPropertyName("orderId")]
+    public Guid? OrderId { get; set; }
+
+    /// <summary>
+    /// Boolean indicating if the notification is a reminder
+    /// </summary>
+    [JsonPropertyName("isReminder")]
+    public bool? IsReminder { get; set; }
+
+    /// <summary>
+    /// The status of the notification
+    /// </summary>
+    [JsonPropertyName("status")]
+    public InitializedNotificationStatusExt Status { get; set; }
+}
+public enum InitializedNotificationStatusExt
+{
+    /// <summary>
+    /// The recipient lookup was successful for at least one recipient
+    /// </summary>
+    Success,
+    /// <summary>
+    /// The recipient lookup failed for all recipients
+    /// </summary>
+    MissingContact,
+    /// <summary>
+    /// The notification order failed to be created due to an error
+    /// </summary>
+    Failure,
+}