Merge pull request #874 from microsoft/readme-patch-1

Add Hidi read me file

Author: darrelmiller

src/Microsoft.OpenApi.Hidi/readme.md

@@ -0,0 +1,91 @@
+# 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
+
+ 
+## 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)  
+	1. 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 
+
+ 
+ 
+ 
+## 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 
+	 
+### 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  
+	• Operations  
+	• Parameters  
+	• Request bodies 
+	• Responses 
+	• Links 
+	• Callbacks 
+	• Schemas 
+	 
+It accepts the following command: 
+
+	• --openapi(-d) - OpenAPI description file path or URL 
+	• --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` 
+
+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:
+
+	• --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 
+	• --clean-ouput(-co) - an optional param that allows a user to overwrite an existing file.  
+	• --version(-v) - OpenAPI specification version 
+	• --format(-f) - File format 
+	• --loglevel(-ll) - The log level to use when logging messages to the main output 
+	• --inline(-i) - Inline $ref instances 
+	• --resolveExternal(-ex) - Resolve 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 
+ 
+ **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 --input 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.