From 37c91300e40739a4fca205cfad19dc493a051c27 Mon Sep 17 00:00:00 2001
From: Magnus Sandgren <5285192+MagnusSandgren@users.noreply.github.com>
Date: Thu, 27 Feb 2025 12:27:47 +0100
Subject: [PATCH] chore(sdk): Add doc (#1975)

---
 .../IDialogTokenValidator.cs                  | 48 ++++++++++++
 .../README.md                                 | 75 +++++++++++++------
 2 files changed, 102 insertions(+), 21 deletions(-)

diff --git a/src/Digdir.Library.Dialogporten.WebApiClient/IDialogTokenValidator.cs b/src/Digdir.Library.Dialogporten.WebApiClient/IDialogTokenValidator.cs
index ebcfadbb2..3b284c7ce 100644
--- a/src/Digdir.Library.Dialogporten.WebApiClient/IDialogTokenValidator.cs
+++ b/src/Digdir.Library.Dialogporten.WebApiClient/IDialogTokenValidator.cs
@@ -3,25 +3,73 @@
 
 namespace Altinn.ApiClients.Dialogporten;
 
+/// <summary>
+/// Represents a service that can validate a dialog token.
+/// </summary>
 public interface IDialogTokenValidator
 {
+    /// <summary>
+    /// Validates a dialog token.
+    /// </summary>
+    /// <param name="token">The token to validate.</param>
+    /// <param name="dialogId">The optional dialog ID associated with the token. If the token does not represent this ID, the validation will fail.</param>
+    /// <param name="requiredActions">The optional list of required actions for the token.</param>
+    /// <param name="options">The optional validation parameters.</param>
+    /// <returns>The result of the validation.</returns>
     IValidationResult Validate(ReadOnlySpan<char> token,
         Guid? dialogId = null,
         string[]? requiredActions = null,
         DialogTokenValidationParameters? options = null);
 }
 
+/// <summary>
+/// Represents the parameters used to validate a dialog token.
+/// </summary>
+/// <remarks>
+/// Global defaults are provided by and can be altered through <see cref="DialogTokenValidationParameters.Default"/>.
+/// </remarks>
 public class DialogTokenValidationParameters
 {
+    /// <summary>
+    /// Gets the default validation parameters which are used when no parameters are provided.
+    /// </summary>
+    /// <remarks>
+    /// This may be altered to change the global default behavior of the validation.
+    /// </remarks>
     public static DialogTokenValidationParameters Default { get; } = new();
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to validate the token's lifetime.
+    /// </summary>
     public bool ValidateLifetime { get; set; } = true;
+
+    /// <summary>
+    /// Gets or sets the clock skew to apply when validating the token's lifetime.
+    /// </summary>
     public TimeSpan ClockSkew { get; set; } = TimeSpan.FromSeconds(10);
 }
 
+/// <summary>
+/// Represents the result of a dialog token validation. 
+/// </summary>
 public interface IValidationResult
 {
+    /// <summary>
+    /// Indicates whether the token is valid based on the validation parameters.
+    /// </summary>
     [MemberNotNullWhen(true, nameof(ClaimsPrincipal))]
     bool IsValid { get; }
+
+    /// <summary>
+    /// A dictionary of errors that occurred during validation.
+    /// </summary>
     Dictionary<string, List<string>> Errors { get; }
+
+    /// <summary>
+    /// The <see cref="ClaimsPrincipal"/> extracted from the token.
+    /// </summary>
+    /// <remarks>
+    /// This property will not be null if the token is valid. It will be null if the token has an invalid format.
+    /// </remarks>
     ClaimsPrincipal? ClaimsPrincipal { get; }
 }
diff --git a/src/Digdir.Library.Dialogporten.WebApiClient/README.md b/src/Digdir.Library.Dialogporten.WebApiClient/README.md
index dc400f372..118c79341 100644
--- a/src/Digdir.Library.Dialogporten.WebApiClient/README.md
+++ b/src/Digdir.Library.Dialogporten.WebApiClient/README.md
@@ -8,39 +8,72 @@ Uses refit IApiResponse on returns.
 
 ## Installation
 
-Install nuget
+Install the [nuget package](https://www.nuget.org/packages/Altinn.ApiClients.Dialogporten) through Package Manager Console:
+```
+Install-Package Altinn.ApiClients.Dialogporten
+```
 
-`dotnet add package Altinn.ApiClients.Dialogporten --version 1.55.2` 
+Or via .NET Core CLI:
+```
+dotnet add package Altinn.ApiClients.Dialogporten
+```
 
 ## Usage
+This package needs some configuration to work. The configuration is done through the `DialogportenSettings` class. The settings are as follows:
+- `BaseUri` - The base URI of the Dialogporten API.
+- `ThrowOnPublicKeyFetchInit` - If true, the client will throw an exception if the public key fetch fails on startup. Default true. 
+- `Maskinporten` - The [Maskinporten settings](https://github.com/Altinn/altinn-apiclient-maskinporten).
+  - `ClientId` - The client ID (secret).
+  - `EncodedJwk` - The encoded JWK (secret).
+  - `Environment` - The environment (test/prod).
+  - `Scope` - Whitespace separated list of scopes to use against Dialogporten. 
 
-This library provides extensions methods providing means to create dialogporten clients.
+### Registering with `IServiceCollection`
+There are two ways to register
 
-Setup
+#### Register through [action parameter](https://learn.microsoft.com/en-us/dotnet/core/extensions/options-library-authors#actiontoptions-parameter):
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddDialogportenClient(x => 
+{
+    x.BaseUri = "https://platform.tt02.altinn.no/dialogporten";
+    // x.ThrowOnPublicKeyFetchInit = false;
+    x.Maskinporten.ClientId = "YOUR_CLIENT_ID";
+    x.Maskinporten.EncodedJwk = "YOUR_ENCODED_JWK";
+    x.Maskinporten.Environment = "test";
+    x.Maskinporten.Scope = "digdir:dialogporten.serviceprovider digdir:dialogporten.serviceprovider.search";
+}
+```
 
-```json
+#### Register through [options instance parameter](https://learn.microsoft.com/en-us/dotnet/core/extensions/options-library-authors#options-instance-parameter):
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+var dialogportenSettings = builder.Configuration
+    .GetSection("DialogportenSettings")
+    .Get<DialogportenSettings>()!;
+builder.Services.AddDialogportenClient(dialogportenSettings);
+```
+In this case, the configuration should look like this:
+```json5
 {
-    "dialogportenSettings": {
-        "BaseUri": "",
-        "ThrowOnPublicKeyFetchInit": "",
+    "DialogportenSettings": {
+        "BaseUri": "https://platform.tt02.altinn.no/dialogporten",
+        // "ThrowOnPublicKeyFetchInit": false,
         "Maskinporten": {
-            "ClientId": "",
-            "Environment": "",
-            "Scope": "",
-            "EncodedJwk": ""
+            "ClientId": "YOUR_CLIENT_ID",
+            "EncodedJwk": "YOUR_ENCODED_JWK",
+            "Environment": "test",
+            "Scope": "digdir:dialogporten.serviceprovider digdir:dialogporten.serviceprovider.search"
         }
     }
 }
 ```
 
-```C#
-var configuration = new ConfigurationBuilder()
-    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
-    .Build();
+### Available services
+The following services are available after registration:
+- [`Altinn.ApiClients.Dialogporten.Features.V1.IServiceownerApi`](./Features/V1/RefitterInterface.cs) - Used to interact with the Dialogporten ServiceOwner API.
+- [`Altinn.ApiClients.Dialogporten.IDialogTokenValidator`](IDialogTokenValidator.cs) - Used to validate Dialogporten tokens.
 
-var services = new ServiceCollection();
+A background service (`IHostedService`) is also registered that periodically fetches the public key from the Dialogporten API. This is required to validate dialog token signatures.
 
-services.AddSingleton<IConfiguration>(configuration);
-
-services.AddDialogportenClient();
-```
+See [sample project](../Digdir.Library.Dialogporten.WebApiClient.WebApiSample/Program.cs) for examples on how to use the services.