Skip to content

Commit d5b8c30

Browse files
Copilotbaywet
Copilot
and
baywet
authored
fix(reader): document parser exceptions with exception tags
Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>
1 parent 3b67916 commit d5b8c30

5 files changed

Lines changed: 55 additions & 46 deletions

File tree

‎src/Microsoft.OpenApi.YamlReader/OpenApiYamlReader.cs‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -59,9 +59,9 @@ public OpenApiYamlReader(OpenApiYamlReaderSettings settings)
5959

6060
/// <inheritdoc/>
6161
/// <remarks>
62-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level YAML
63-
/// errors can throw before a <see cref="ReadResult"/> is created.
62+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
6463
/// </remarks>
64+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
6565
public async Task<ReadResult> ReadAsync(Stream input,
6666
Uri location,
6767
OpenApiReaderSettings settings,
@@ -100,9 +100,9 @@ await CopyToMemoryStreamAsync(
100100

101101
/// <inheritdoc/>
102102
/// <remarks>
103-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level YAML
104-
/// errors can throw before a <see cref="ReadResult"/> is created.
103+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
105104
/// </remarks>
105+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
106106
public ReadResult Read(MemoryStream input,
107107
Uri location,
108108
OpenApiReaderSettings settings)
@@ -203,9 +203,9 @@ public static ReadResult Read(JsonNode jsonNode, Uri location, OpenApiReaderSett
203203

204204
/// <inheritdoc/>
205205
/// <remarks>
206-
/// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>. Syntax-level YAML
207-
/// errors can throw before a fragment is created.
206+
/// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>.
208207
/// </remarks>
208+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a fragment is created.</exception>
209209
public T? ReadFragment<T>(MemoryStream input,
210210
OpenApiSpecVersion version,
211211
OpenApiDocument openApiDocument,

‎src/Microsoft.OpenApi/Interfaces/IOpenApiReader.cs‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,10 @@ public interface IOpenApiReader
2323
/// <param name="cancellationToken">Propagates notification that an operation should be cancelled.</param>
2424
/// <returns></returns>
2525
/// <remarks>
26-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
27-
/// errors can throw before a <see cref="ReadResult"/> is created.
26+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
2827
/// </remarks>
28+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
29+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
2930
Task<ReadResult> ReadAsync(Stream input, Uri location, OpenApiReaderSettings settings, CancellationToken cancellationToken = default);
3031

3132
/// <summary>
@@ -36,9 +37,10 @@ public interface IOpenApiReader
3637
/// <param name="settings"></param>
3738
/// <returns></returns>
3839
/// <remarks>
39-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
40-
/// errors can throw before a <see cref="ReadResult"/> is created.
40+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
4141
/// </remarks>
42+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
43+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
4244
ReadResult Read(MemoryStream input, Uri location, OpenApiReaderSettings settings);
4345

4446
/// <summary>
@@ -51,9 +53,10 @@ public interface IOpenApiReader
5153
/// <param name="settings">The OpenApiReader settings.</param>
5254
/// <returns>Instance of newly created IOpenApiElement.</returns>
5355
/// <remarks>
54-
/// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>. Syntax-level JSON or YAML
55-
/// errors can throw before a fragment is created.
56+
/// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>.
5657
/// </remarks>
58+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a fragment is created.</exception>
59+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a fragment is created.</exception>
5760
T? ReadFragment<T>(MemoryStream input, OpenApiSpecVersion version, OpenApiDocument openApiDocument, out OpenApiDiagnostic diagnostic, OpenApiReaderSettings? settings = null) where T : IOpenApiElement;
5861
}
5962
}

‎src/Microsoft.OpenApi/Models/OpenApiDocument.cs‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -733,9 +733,10 @@ private static bool TryGetPlainNameFragment(string reference, out string fragmen
733733
/// <param name="settings">The OpenApi reader settings.</param>
734734
/// <returns></returns>
735735
/// <remarks>
736-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
737-
/// errors can throw before a <see cref="ReadResult"/> is created.
736+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
738737
/// </remarks>
738+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
739+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
739740
public static ReadResult Load(MemoryStream stream,
740741
string? format = null,
741742
OpenApiReaderSettings? settings = null)
@@ -751,9 +752,10 @@ public static ReadResult Load(MemoryStream stream,
751752
/// <param name="token">The cancellation token</param>
752753
/// <returns></returns>
753754
/// <remarks>
754-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
755-
/// errors can throw before a <see cref="ReadResult"/> is created.
755+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
756756
/// </remarks>
757+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
758+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
757759
public static async Task<ReadResult> LoadAsync(string url, OpenApiReaderSettings? settings = null, CancellationToken token = default)
758760
{
759761
return await OpenApiModelFactory.LoadAsync(url, settings, token).ConfigureAwait(false);
@@ -768,9 +770,10 @@ public static async Task<ReadResult> LoadAsync(string url, OpenApiReaderSettings
768770
/// <param name="cancellationToken">Propagates information about operation cancelling.</param>
769771
/// <returns></returns>
770772
/// <remarks>
771-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
772-
/// errors can throw before a <see cref="ReadResult"/> is created.
773+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
773774
/// </remarks>
775+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
776+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
774777
public static async Task<ReadResult> LoadAsync(Stream stream, string? format = null, OpenApiReaderSettings? settings = null, CancellationToken cancellationToken = default)
775778
{
776779
return await OpenApiModelFactory.LoadAsync(stream, format, settings, cancellationToken).ConfigureAwait(false);
@@ -785,9 +788,10 @@ public static async Task<ReadResult> LoadAsync(Stream stream, string? format = n
785788
/// <param name="settings"></param>
786789
/// <returns></returns>
787790
/// <remarks>
788-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
789-
/// errors can throw before a <see cref="ReadResult"/> is created.
791+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
790792
/// </remarks>
793+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
794+
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
791795
public static ReadResult Parse(string input,
792796
string? format = null,
793797
OpenApiReaderSettings? settings = null)

‎src/Microsoft.OpenApi/Reader/OpenApiJsonReader.cs‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@ public class OpenApiJsonReader : IOpenApiReader
2424
/// <param name="settings">The Reader settings to be used during parsing.</param>
2525
/// <returns></returns>
2626
/// <remarks>
27-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON
28-
/// errors can throw before a <see cref="ReadResult"/> is created.
27+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
2928
/// </remarks>
29+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
3030
public ReadResult Read(MemoryStream input,
3131
Uri location,
3232
OpenApiReaderSettings settings)
@@ -128,9 +128,9 @@ public ReadResult Read(JsonNode jsonNode,
128128
/// <param name="cancellationToken">Propagates notifications that operations should be cancelled.</param>
129129
/// <returns></returns>
130130
/// <remarks>
131-
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON
132-
/// errors can throw before a <see cref="ReadResult"/> is created.
131+
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
133132
/// </remarks>
133+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
134134
public async Task<ReadResult> ReadAsync(Stream input,
135135
Uri location,
136136
OpenApiReaderSettings settings,
@@ -164,9 +164,9 @@ public async Task<ReadResult> ReadAsync(Stream input,
164164

165165
/// <inheritdoc/>
166166
/// <remarks>
167-
/// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>. Syntax-level JSON
168-
/// errors can throw before a fragment is created.
167+
/// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>.
169168
/// </remarks>
169+
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a fragment is created.</exception>
170170
public T? ReadFragment<T>(MemoryStream input,
171171
OpenApiSpecVersion version,
172172
OpenApiDocument openApiDocument,

0 commit comments

Comments
 (0)