Merge branch 'main' into mw/use-http-method-object-instead-of-enum

Author: baywet

docs/images/workbench.png

@@ -17,21 +17,22 @@ Install [Microsoft.OpenApi.Hidi](https://www.nuget.org/packages/Microsoft.OpenAp
 
 ### .NET CLI(Global)
 
-	1. dotnet tool install --global Microsoft.OpenApi.Hidi --prerelease
-
+```bash
+dotnet tool install --global Microsoft.OpenApi.Hidi --prerelease
+```
 
 ### .NET CLI(local)
- 
-	1. dotnet new tool-manifest #if you are setting up the OpenAPI.NET repo 
-	2. dotnet tool install --local Microsoft.OpenApi.Hidi --prerelease 
 
+```bash 
+dotnet new tool-manifest #if you are setting up the OpenAPI.NET repo 
+dotnet tool install --local Microsoft.OpenApi.Hidi --prerelease 
+```
 
 
 
 ## How to use Hidi
 
-Once you've installed the package locally, you can invoke the Hidi by running: hidi [command]. 
-You can access the list of command options we have by running hidi -h 
+Once you've installed the package locally, you can invoke the Hidi by running: `hidi [command]`. You can access the list of command options we have by running `hidi -h` 
 The tool avails the following commands: 
 
 	• Validate  
@@ -57,63 +58,84 @@ It accepts the following command:
 	• --loglevel(-ll) - The log level to use when logging messages to the main output 
 	 
 
-**Example:** `hidi.exe validate --openapi C:\OpenApidocs\Mail.yml --loglevel trace` 
+#### Example:
 
-Run validate -h to see the options available.
+```bash
+hidi validate --openapi C:\OpenApidocs\Mail.yml --loglevel trace` 
+```
+
+> Run `hidi validate -h` to see the options available.
 
 ### Transform
 
 Used to convert file formats from JSON to YAML and vice versa and performs slicing of OpenAPI documents. 
 
 This command accepts the following parameters:
 
-	• --openapi(-d) - OpenAPI description file path in the local filesystem or a valid URL hosted on a HTTPS server 
-	• --csdl(--cs) - CSDL file path in the local filesystem or a valid URL hosted on a HTTPS server 
-	• --csdlfilter(--csf) - a filter parameter that a user can use to select a subset of a large CSDL file. They do so by providing a comma delimited list of EntitySet and Singleton names that appear in the EntityContainer. 
-	• --output(-o) - Output directory path for the transformed document.
-    • --output-folder(--of) - The output directory path for the generated files.
-	• --clean-ouput(--co) - an optional param that allows a user to overwrite an existing file.  
-	• --version(-v) - OpenAPI specification version.
-    • --metadata-version(--mv) - the metadata version to use.
-	• --format(-f) - File format 
-    • --terse-output(--to) - Produce terse json output
-    • --settings-path(--sp) - The configuration file with CSDL conversion settings.
-	• --loglevel(--ll) - The log level to use when logging messages to the main output 
-	• --inline-local - Inline local $ref instances 
-	• --inline-external(--ex) - Inline external $refs 
-	• --filterByOperationIds(--op) - Slice document based on OperationId(s) provided. Accepts a comma delimited list of operation ids. 
-	• --filterByTags(-t) - Slice document based on tag(s) provided. Accepts a comma delimited list of tags. 
-	• --filterByCollection(-c) - Slices the OpenAPI document based on the Postman Collection file generated by Resource Explorer 
-    • --manifest (-m) - Slices the OpenAPI document based on the requests defined in the API Manifest file referenced by the provided URI. For API manifests with multiple API Dependenties, use a fragment identifier to select the desired one. e.g ./apimanifest.json#example
+
+	• --openapi, (-d) - OpenAPI description file path in the local filesystem or a valid URL hosted on a HTTPS server 
+	• --csdl (--cs) - CSDL file path in the local filesystem or a valid URL hosted on a HTTPS server 
+	• --csdl-filter (--csf) - a filter parameter that a user can use to select a subset of a large CSDL file. They do so by providing a comma delimited list of EntitySet and Singleton names that appear in the EntityContainer. 
+	• --output (-o) - Output directory path for the transformed document.
+	• --clean-output (--co) - an optional param that allows a user to overwrite an existing file.  
+	• --version (-v) - OpenAPI specification version.
+    • --metadata-version (--mv) - the metadata version to use.
+	• --format (-f) - File format 
+    • --terse-output (--to) - Produce terse json output
+    • --settings-path (--sp) - The configuration file with CSDL conversion settings.
+	• --log-level (--ll) - The log level to use when logging messages to the main output 
+	• --inline-local (--il) - Inline local $ref instances 
+	• --inline-external (--ie) - Inline external $refs instances
+	• --filter-by-operationids(--op) - Slice document based on OperationId(s) provided. Accepts a comma delimited list of operation ids. 
+	• --filter-by-tags (--t) - Slice document based on tag(s) provided. Accepts a comma delimited list of tags. 
+	• --filter-by-collection (-c) - Slices the OpenAPI document based on the Postman Collection file generated by Resource Explorer 
 
- **Examples:**  
+ #### Examples:  
 
-	1. Filtering by OperationIds  
-	hidi transform -d files\People.yml -f yaml -o files\People.yml -v OpenApi3_0 --op users_UpdateInsights --co 
-	 
-	2. Filtering by Postman collection 
-	hidi transform --openapi files\People.yml --format yaml --output files\People2.yml --version OpenApi3_0 --filterByCollection Graph-Collection-0017059134807617005.postman_collection.json 
-	 
-	3. CSDL--->OpenAPI conversion and filtering 
-	hidi transform --csdl Files/Todo.xml --output Files/Todo-subset.yml --format yaml --version OpenApi3_0 --filterByOperationIds Todos.Todo.UpdateTodo 
-	 
-	4. CSDL Filtering by EntitySets and Singletons 
-	hidi transform --cs dataverse.csdl --csdlFilter "appointments,opportunities" -o appointmentsAndOpportunities.yaml --ll trace 
-	 
-Run transform -h to see all the available usage options.
+1. Filtering by OperationIds  
+
+```bash
+hidi transform -d files\People.yml -f yaml -o files\People.yml -v OpenApi3_0 --op users_UpdateInsights --co 
+```
+
+2. Filtering by Postman collection 
+
+```bash	
+hidi transform --openapi files\People.yml --format yaml --output files\People2.yml --version OpenApi3_0 --filter-by-collection Graph-Collection-0017059134807617005.postman_collection.json 
+```
+
+3. CSDL--->OpenAPI conversion and filtering 
+
+```bash
+hidi transform --csdl Files/Todo.xml --output Files/Todo-subset.yml --format yaml --version OpenApi3_0 --filter-by-operationids Todos.Todo.UpdateTodo 
+```	 
+	
+4. CSDL Filtering by EntitySets and Singletons 
+
+```bash
+hidi transform --cs dataverse.csdl --csdl-filter "appointments,opportunities" -o appointmentsAndOpportunities.yaml --ll trace 
+```
+
+> Run `hidi transform -h` to see all the available usage options.
 
 ### Show
 
 This command accepts an OpenAPI document as an input parameter and generates a Markdown file that contains a diagram of the API using Mermaid syntax.
 
-**Examples:**
+#### Examples:
 
-    1. hidi show -d files\People.yml -o People.md -ll trace
+```bash
+hidi show -d files\People.yml -o People.md -ll trace
+```
 
 ### Plugin
 
 This command generates an OpenAI style Plugin manifest and minimal OpenAPI file based on the provided API Manifest
 
-**Examples:**
+#### Examples:
+
+```bash
+hidi plugin -m exampleApiManifest.yml -o mypluginfolder 
+```
 
-    1. hidi plugin -m exampleApiManifest.yml -o mypluginfolder 
+> Run `hidi plugin -h` to see all the available usage options.

src/Microsoft.OpenApi.Hidi/readme.md

@@ -11,9 +11,9 @@
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Reader;
-using Microsoft.OpenApi.Readers;
 using Microsoft.OpenApi.Services;
 using Microsoft.OpenApi.Validations;
+using Microsoft.OpenApi.Writers;
 
 namespace Microsoft.OpenApi.Workbench
 {
@@ -242,7 +242,7 @@ internal async Task ParseDocumentAsync()
                         : new("file://" + Path.GetDirectoryName(_inputFile) + "/");
                 }
 
-                var readResult = await OpenApiDocument.LoadAsync(stream, Format.GetDisplayName());
+                var readResult = await OpenApiDocument.LoadAsync(stream, Format.GetDisplayName().ToLowerInvariant(), settings);
                 var document = readResult.Document;
                 var context = readResult.Diagnostic;
 
@@ -298,13 +298,13 @@ internal async Task ParseDocumentAsync()
         /// </summary>
         private async Task<string> WriteContentsAsync(OpenApiDocument document)
         {
-            var outputStream = new MemoryStream();
+            using var outputStream = new MemoryStream();
 
             await document.SerializeAsync(
                 outputStream,
                 Version,
                 Format,
-                (Writers.OpenApiWriterSettings)new()
+                new OpenApiWriterSettings()
                 {
                     InlineLocalReferences = InlineLocal,
                     InlineExternalReferences = InlineExternal

src/Microsoft.OpenApi.Workbench/MainModel.cs

@@ -8,7 +8,7 @@
 
 namespace Microsoft.OpenApi.Readers.Tests.V31Tests
 {
-    public class OpenApiCompoentsTests
+    public class OpenApiComponentsTests
     {
         [Theory]
         [InlineData("./FirstLevel/SecondLevel/ThridLevel/File.json#/components/schemas/ExternalRelativePathModel", "ExternalRelativePathModel", "./FirstLevel/SecondLevel/ThridLevel/File.json")]

test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiCompoentsTests.cs renamed to test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiComponentsTests.cs

@@ -575,5 +575,20 @@ public void ParseEmptyMemoryStreamThrowsAnArgumentException()
         {
             Assert.Throws<ArgumentException>(() => OpenApiDocument.Load(new MemoryStream()));
         }
+
+        [Fact]
+        public async Task ValidateReferencedExampleInSchemaWorks()
+        {
+            // Arrange && Act
+            var path = Path.Combine(SampleFolderPath, "docWithReferencedExampleInSchemaWorks.yaml");
+            var result = await OpenApiDocument.LoadAsync(path, SettingsFixture.ReaderSettings);
+            var actualSchemaExample = result.Document.Components.Schemas["DiffCreatedEvent"].Properties["updatedAt"].Example;
+            var targetSchemaExample = result.Document.Components.Schemas["Timestamp"].Example;
+
+            // Assert
+            Assert.Equal(targetSchemaExample, actualSchemaExample);
+            Assert.Empty(result.Diagnostic.Errors);
+            Assert.Empty(result.Diagnostic.Warnings);            
+        }
     }
 }

test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDocumentTests.cs

@@ -0,0 +1,30 @@
+openapi: 3.1.1
+info:
+  title: ReferenceById
+  version: 1.0.0
+paths:
+  /resource:
+    get:
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DiffCreatedEvent'
+components:
+  schemas:
+    DiffCreatedEvent:
+      description: 'diff index created'
+      type: object
+      additionalProperties: false
+      properties:
+        updatedAt:        
+          $ref: '#/components/schemas/Timestamp'
+      example:        
+          "updatedAt": '2020-06-30T06:43:51.391Z'        
+    Timestamp:      
+        type: string 
+        format: date-time 
+        description: 'timestamp' 
+        example: '2020-06-30T06:43:51.391Z' 

test/Microsoft.OpenApi.Readers.Tests/V31Tests/Samples/OpenApiDocument/docWithReferencedExampleInSchemaWorks.yaml

@@ -6,9 +6,12 @@
 using System.Globalization;
 using System.IO;
 using System.Linq;
+using System.Net;
 using System.Net.Http;
+using System.Net.Http.Headers;
 using System.Text;
 using System.Text.Json.Nodes;
+using System.Threading;
 using System.Threading.Tasks;
 using FluentAssertions;
 using Microsoft.OpenApi.Extensions;
@@ -21,6 +24,8 @@
 using Microsoft.OpenApi.Validations;
 using Microsoft.OpenApi.Validations.Rules;
 using Microsoft.OpenApi.Writers;
+using Moq;
+using Moq.Protected;
 using Xunit;
 
 namespace Microsoft.OpenApi.Readers.Tests.V3Tests
@@ -29,8 +34,6 @@ namespace Microsoft.OpenApi.Readers.Tests.V3Tests
     public class OpenApiDocumentTests
     {
         private const string SampleFolderPath = "V3Tests/Samples/OpenApiDocument/";
-        private const string codacyApi = "https://api.codacy.com/api/api-docs/swagger.yaml";
-
         private static async Task<T> CloneAsync<T>(T element) where T : class, IOpenApiSerializable
         {
             using var stream = new MemoryStream();
@@ -1494,8 +1497,24 @@ public async Task ParseDocumentWithExampleReferencesPasses()
         [Fact]
         public async Task ParseDocumentWithNonStandardMIMETypePasses()
         {
+            var path = Path.Combine(SampleFolderPath, "basicDocumentWithMultipleServers.yaml");
+            using var stream = Resources.GetStream(path);
+            using var streamReader = new StreamReader(stream);
+            var contentAsString = await streamReader.ReadToEndAsync();
+            var mockMessageHandler = new Mock<HttpMessageHandler>();
+            mockMessageHandler.Protected()
+                .Setup<Task<HttpResponseMessage>>("SendAsync", ItExpr.IsAny<HttpRequestMessage>(), ItExpr.IsAny<CancellationToken>())
+                .ReturnsAsync(new HttpResponseMessage {
+                    StatusCode = HttpStatusCode.OK,
+                    Content = new StringContent(contentAsString, new MediaTypeHeaderValue("text/x-yaml"))
+                });
+            var settings = new OpenApiReaderSettings
+            {
+                HttpClient = new HttpClient(mockMessageHandler.Object)
+            };
+            settings.AddYamlReader();
             // Act & Assert: Ensure NotSupportedException is not thrown for non-standard MIME type: text/x-yaml
-            var result = await OpenApiDocument.LoadAsync(codacyApi, SettingsFixture.ReaderSettings);
+            var result = await OpenApiDocument.LoadAsync("https://localhost/doesntmatter/foo.bar", settings);
             Assert.NotNull(result.Document); 
         }
     }

test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiDocumentTests.cs

@@ -14,7 +14,7 @@
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.13.0" />
     <PackageReference Include="Moq" Version="4.20.72" />
     <PackageReference Include="SharpYaml" Version="2.1.1" />
-    <PackageReference Include="Verify.Xunit" Version="28.13.0" />
+    <PackageReference Include="Verify.Xunit" Version="28.14.1" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.0.2" PrivateAssets="all" />
     <PackageReference Include="Microsoft.CSharp" Version="4.7.0" />