Skip to content

Commit

Permalink
fix: add documentation for problem-details (#128)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Alxandr
Alxandr authored Aug 27, 2024
1 parent 273ecf3 commit 9eca254
Show file tree
Hide file tree
Showing 4 changed files with 68 additions and 15 deletions.
9 changes: 9 additions & 0 deletions ...zation.ProblemDetails/src/ProblemDetails.Abstractions/ValidationErrorBuilderExtensions.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDe
/// <param name="errors">The error collection.</param>
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="path">The path.</param>
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDescriptor descriptor, string path)
=> errors.Add(descriptor.Create(path));

Expand All @@ -31,6 +32,7 @@ public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDe
/// <param name="errors">The error collection.</param>
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="paths">The paths.</param>
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDescriptor descriptor, ImmutableArray<string> paths)
=> errors.Add(descriptor.Create(paths));

Expand All @@ -40,6 +42,7 @@ public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDe
/// <param name="errors">The error collection.</param>
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="paths">The paths.</param>
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDescriptor descriptor, IEnumerable<string> paths)
=> errors.Add(descriptor.Create(paths));

Expand Down Expand Up @@ -68,6 +71,7 @@ public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDe
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="path">The path.</param>
/// <param name="extensions">The extensions.</param>
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDescriptor descriptor, string path, ProblemExtensionData extensions)
=> errors.Add(descriptor.Create(path, extensions));

Expand All @@ -78,6 +82,7 @@ public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDe
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="path">The path.</param>
/// <param name="extensions">The extensions.</param>
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDescriptor descriptor, string path, IReadOnlyDictionary<string, string> extensions)
=> errors.Add(descriptor.Create(path, extensions));

Expand All @@ -88,6 +93,7 @@ public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDe
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="paths">The paths.</param>
/// <param name="extensions">The extensions.</param>
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDescriptor descriptor, ImmutableArray<string> paths, ProblemExtensionData extensions)
=> errors.Add(descriptor.Create(paths, extensions));

Expand All @@ -98,6 +104,7 @@ public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDe
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="paths">The paths.</param>
/// <param name="extensions">The extensions.</param>
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDescriptor descriptor, ImmutableArray<string> paths, IReadOnlyDictionary<string, string> extensions)
=> errors.Add(descriptor.Create(paths, extensions));

Expand All @@ -108,6 +115,7 @@ public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDe
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="paths">The paths.</param>
/// <param name="extensions">The extensions.</param>
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDescriptor descriptor, IEnumerable<string> paths, ProblemExtensionData extensions)
=> errors.Add(descriptor.Create(paths, extensions));

Expand All @@ -118,6 +126,7 @@ public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDe
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="paths">The paths.</param>
/// <param name="extensions">The extensions.</param>
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static void Add(this ref ValidationErrorBuilder errors, ValidationErrorDescriptor descriptor, IEnumerable<string> paths, IReadOnlyDictionary<string, string> extensions)
=> errors.Add(descriptor.Create(paths, extensions));
}
61 changes: 49 additions & 12 deletions ...n.Authorization.ProblemDetails/src/ProblemDetails.Abstractions/ValidationErrorInstance.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="path">The path.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, string path)
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, string path)
=> new ValidationErrorInstance(descriptor, paths: [path], extensions: []);

/// <summary>
Expand All @@ -32,7 +33,8 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="paths">The paths.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, ImmutableArray<string> paths)
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, ImmutableArray<string> paths)
=> new ValidationErrorInstance(descriptor, paths: paths, extensions: []);

/// <summary>
Expand All @@ -41,7 +43,8 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="paths">The paths.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, IEnumerable<string> paths)
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, IEnumerable<string> paths)
=> new ValidationErrorInstance(descriptor, paths: [.. paths], extensions: []);

/// <summary>
Expand All @@ -50,7 +53,7 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="extensions">The extensions.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, ProblemExtensionData extensions)
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, ProblemExtensionData extensions)
=> new ValidationErrorInstance(descriptor, paths: [], extensions: extensions);

/// <summary>
Expand All @@ -59,7 +62,7 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="descriptor">The <see cref="ValidationErrorDescriptor"/>.</param>
/// <param name="extensions">The extensions.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, IReadOnlyDictionary<string, string> extensions)
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, IReadOnlyDictionary<string, string> extensions)
=> new ValidationErrorInstance(descriptor, paths: [], extensions: [.. extensions]);

/// <summary>
Expand All @@ -69,7 +72,8 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="path">The path.</param>
/// <param name="extensions">The extensions.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, string path, ProblemExtensionData extensions)
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, string path, ProblemExtensionData extensions)
=> new ValidationErrorInstance(descriptor, paths: [path], extensions: extensions);

/// <summary>
Expand All @@ -79,7 +83,8 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="path">The path.</param>
/// <param name="extensions">The extensions.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, string path, IReadOnlyDictionary<string, string> extensions)
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, string path, IReadOnlyDictionary<string, string> extensions)
=> new ValidationErrorInstance(descriptor, paths: [path], extensions: [.. extensions]);

/// <summary>
Expand All @@ -89,7 +94,8 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="paths">The paths.</param>
/// <param name="extensions">The extensions.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, ImmutableArray<string> paths, ProblemExtensionData extensions)
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, ImmutableArray<string> paths, ProblemExtensionData extensions)
=> new ValidationErrorInstance(descriptor, paths: paths, extensions: extensions);

/// <summary>
Expand All @@ -99,7 +105,8 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="paths">The paths.</param>
/// <param name="extensions">The extensions.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, ImmutableArray<string> paths, IReadOnlyDictionary<string, string> extensions)
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, ImmutableArray<string> paths, IReadOnlyDictionary<string, string> extensions)
=> new ValidationErrorInstance(descriptor, paths: paths, extensions: [.. extensions]);

/// <summary>
Expand All @@ -109,7 +116,8 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="paths">The paths.</param>
/// <param name="extensions">The extensions.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, IEnumerable<string> paths, ProblemExtensionData extensions)
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, IEnumerable<string> paths, ProblemExtensionData extensions)
=> new ValidationErrorInstance(descriptor, paths: [.. paths], extensions: extensions);

/// <summary>
Expand All @@ -119,7 +127,8 @@ public static ValidationErrorInstance Create(ValidationErrorDescriptor descripto
/// <param name="paths">The paths.</param>
/// <param name="extensions">The extensions.</param>
/// <returns>A <see cref="ValidationErrorInstance"/>.</returns>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, IEnumerable<string> paths, IReadOnlyDictionary<string, string> extensions)
/// <inheritdoc cref="ValidationErrorInstance.Paths" path="/remarks"/>
public static ValidationErrorInstance Create(ValidationErrorDescriptor descriptor, IEnumerable<string> paths, IReadOnlyDictionary<string, string> extensions)
=> new ValidationErrorInstance(descriptor, paths: [.. paths], extensions: [.. extensions]);

private readonly ValidationErrorDescriptor _descriptor;
Expand Down Expand Up @@ -152,7 +161,35 @@ internal ValidationErrorInstance(
/// Gets the error paths.
/// </summary>
/// <remarks>
/// This SHOULD be a set of JSON Pointer values that identify the path(s) to the erroneous field(s) within the request document or parameters.
/// The paths SHOULD be a set of JSON Pointer values that identify the path(s) to the erroneous field(s) within the request document or parameters.
///
/// A few examples of JSON Pointers:
/// <list type="table">
/// <listheader>
/// <term>Path</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term><c>/foo/bar</c></term>
/// <description>The json field <c>foo.bar</c> in the body.</description>
/// </item>
/// <item>
/// <term><c>/$QUERY/baz</c></term>
/// <description>The query parameter <c>baz</c>.</description>
/// </item>
/// <item>
/// <term><c>/$HEADER/x-value</c></term>
/// <description>The header <c>X-Value</c> (headers are case insensitive, so it's lowercased).</description>
/// </item>
/// <item>
/// <term><c>/$HEADER/authorization/bearer</c></term>
/// <description>The bearer token value in a authorization header.</description>
/// </item>
/// <item>
/// <term><c>/$PATH/id</c></term>
/// <description>The path parameter <c>id</c>.</description>
/// </item>
/// </list>
/// </remarks>
public ImmutableArray<string> Paths => _paths;

Expand Down
Loading

0 comments on commit 9eca254

Please sign in to comment.