Merge pull request #1113 from microsoft/dm/show

Adds support for generating Mermaid diagrams from APIs

Author: darrelmiller

src/Microsoft.OpenApi.Hidi/Handlers/ShowCommandHandler.cs

@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System;
+using System.CommandLine;
+using System.CommandLine.Invocation;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.OpenApi.Hidi.Handlers
+{
+    internal class ShowCommandHandler : ICommandHandler
+    {
+        public Option<string> DescriptionOption { get; set; }
+        public Option<FileInfo> OutputOption { get; set; }
+        public Option<LogLevel> LogLevelOption { get; set; }
+        public Option<string> CsdlOption { get; set; }
+        public Option<string> CsdlFilterOption { get; set; }
+
+
+        public int Invoke(InvocationContext context)
+        {
+            return InvokeAsync(context).GetAwaiter().GetResult();
+        }
+        public async Task<int> InvokeAsync(InvocationContext context)
+        {
+            string openapi = context.ParseResult.GetValueForOption(DescriptionOption);
+            FileInfo output = context.ParseResult.GetValueForOption(OutputOption);
+            LogLevel logLevel = context.ParseResult.GetValueForOption(LogLevelOption);
+            string csdlFilter = context.ParseResult.GetValueForOption(CsdlFilterOption);
+            string csdl = context.ParseResult.GetValueForOption(CsdlOption);
+            CancellationToken cancellationToken = (CancellationToken)context.BindingContext.GetService(typeof(CancellationToken));
+
+            using var loggerFactory = Logger.ConfigureLogger(logLevel);
+            var logger = loggerFactory.CreateLogger<OpenApiService>();
+            try
+            {
+                await OpenApiService.ShowOpenApiDocument(openapi, csdl, csdlFilter, output, logger, cancellationToken);
+
+                return 0;
+            }
+            catch (Exception ex)
+            {
+#if DEBUG
+                logger.LogCritical(ex, ex.Message);
+                throw; // so debug tools go straight to the source of the exception when attached
+#else
+                logger.LogCritical( ex.Message);
+                return 1;
+#endif
+            }
+        }
+    }
+}

src/Microsoft.OpenApi.Hidi/Handlers/TransformCommandHandler.cs

@@ -57,7 +57,7 @@ public async Task<int> InvokeAsync(InvocationContext context)
             var logger = loggerFactory.CreateLogger<OpenApiService>();
             try
             {
-                await OpenApiService.TransformOpenApiDocument(openapi, csdl, csdlFilter, output, cleanOutput, version, format, terseOutput, settingsFile, logLevel, inlineLocal, inlineExternal, filterbyoperationids, filterbytags, filterbycollection, cancellationToken);
+                await OpenApiService.TransformOpenApiDocument(openapi, csdl, csdlFilter, output, cleanOutput, version, format, terseOutput, settingsFile, inlineLocal, inlineExternal, filterbyoperationids, filterbytags, filterbycollection, logger, cancellationToken);
 
                 return 0;
             }

src/Microsoft.OpenApi.Hidi/Handlers/ValidateCommandHandler.cs

@@ -30,7 +30,7 @@ public async Task<int> InvokeAsync(InvocationContext context)
             var logger = loggerFactory.CreateLogger<OpenApiService>();
             try
             {
-                await OpenApiService.ValidateOpenApiDocument(openapi, logLevel, cancellationToken);
+                await OpenApiService.ValidateOpenApiDocument(openapi, logger, cancellationToken);
                 return 0;
             }
             catch (Exception ex)

src/Microsoft.OpenApi.Hidi/OpenApiService.cs

@@ -16,8 +16,17 @@ namespace Microsoft.OpenApi.Hidi
     static class Program
     {
         static async Task Main(string[] args)
-        {            
-            var rootCommand = new RootCommand() {};
+        {
+            var rootCommand = CreateRootCommand();
+
+            // Parse the incoming args and invoke the handler
+            await rootCommand.InvokeAsync(args);
+
+        }
+
+        internal static RootCommand CreateRootCommand()
+        {
+            var rootCommand = new RootCommand() { };
 
             // command option parameters and aliases
             var descriptionOption = new Option<string>("--openapi", "Input OpenAPI description file path or URL");
@@ -46,7 +55,7 @@ static async Task Main(string[] args)
 
             var settingsFileOption = new Option<string>("--settings-path", "The configuration file with CSDL conversion settings.");
             settingsFileOption.AddAlias("--sp");
-            
+
             var logLevelOption = new Option<LogLevel>("--log-level", () => LogLevel.Information, "The log level to use when logging messages to the main output.");
             logLevelOption.AddAlias("--ll");
 
@@ -71,7 +80,7 @@ static async Task Main(string[] args)
                 logLevelOption
             };
 
-            validateCommand.Handler = new ValidateCommandHandler 
+            validateCommand.Handler = new ValidateCommandHandler
             {
                 DescriptionOption = descriptionOption,
                 LogLevelOption = logLevelOption
@@ -88,7 +97,7 @@ static async Task Main(string[] args)
                 formatOption,
                 terseOutputOption,
                 settingsFileOption,
-                logLevelOption,               
+                logLevelOption,
                 filterByOperationIdsOption,
                 filterByTagsOption,
                 filterByCollectionOption,
@@ -115,14 +124,29 @@ static async Task Main(string[] args)
                 InlineExternalOption = inlineExternalOption
             };
 
+            var showCommand = new Command("show")
+            {
+                descriptionOption,
+                csdlOption,
+                csdlFilterOption,
+                logLevelOption,
+                outputOption,
+                cleanOutputOption
+            };
+
+            showCommand.Handler = new ShowCommandHandler
+            {
+                DescriptionOption = descriptionOption,
+                CsdlOption = csdlOption,
+                CsdlFilterOption = csdlFilterOption,
+                OutputOption = outputOption,
+                LogLevelOption = logLevelOption
+            };
+
+            rootCommand.Add(showCommand);
             rootCommand.Add(transformCommand);
             rootCommand.Add(validateCommand);
-            
-            // Parse the incoming args and invoke the handler
-            await rootCommand.InvokeAsync(args);
-
-            //// Wait for logger to write messages to the console before exiting
-            await Task.Delay(10);
-        }        
+            return rootCommand;
+        }
     }
 }

src/Microsoft.OpenApi.Hidi/Program.cs

@@ -1,24 +1,26 @@
-# Overview 
+# Overview
 
 Hidi is a command line tool that makes it easy to work with and transform OpenAPI documents. The tool enables you validate and apply transformations to and from different file formats using various commands to do different actions on the files.
 
 ## Capabilities
+
 Hidi has these key capabilities that enable you to build different scenarios off the tool
 
 	• Validation of OpenAPI files 
 	• Conversion of OpenAPI files into different file formats: convert files from JSON to YAML, YAML to JSON
 	• Slice or filter OpenAPI documents to smaller subsets using operationIDs and tags
+    • Generate a Mermaid diagram of the API from an OpenAPI document
 
- 
-## Installation 
+## Installation
 
 Install [Microsoft.OpenApi.Hidi](https://www.nuget.org/packages/Microsoft.OpenApi.Hidi/1.0.0-preview4) package from NuGet by running the following command:  
 
-### .NET CLI(Global)  
+### .NET CLI(Global)
+
 	1. dotnet tool install --global Microsoft.OpenApi.Hidi --prerelease
 
 
-### .NET CLI(local) 
+### .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 
@@ -27,14 +29,17 @@ Install [Microsoft.OpenApi.Hidi](https://www.nuget.org/packages/Microsoft.OpenAp
 
 
 ## 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 
 The tool avails the following commands: 
 
 	• Validate  
 	• Transform 
+	• Show
 	 
-### Validate 
+### Validate
+
 This command option accepts an OpenAPI document as an input parameter, visits multiple OpenAPI elements within the document and returns statistics count report on the following elements: 
 
 	• Path Items  
@@ -54,9 +59,10 @@ It accepts the following command:
 
 **Example:** `hidi.exe validate --openapi C:\OpenApidocs\Mail.yml --loglevel trace` 
 
-Run validate -h to see the options available. 
- 
-### Transform 
+Run 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:
@@ -90,3 +96,11 @@ This command accepts the following parameters:
 	hidi transform -cs dataverse.csdl --csdlFilter "appointments,opportunities" -o appointmentsAndOpportunities.yaml -ll trace 
 	 
 Run 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:**
+
+    1. hidi show -d files\People.yml -o People.md -ll trace