Microsoft.OpenApi.Hidi 2.0.0-preview3

Prefix Reserved
This is a prerelease version of Microsoft.OpenApi.Hidi.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet tool install --global Microsoft.OpenApi.Hidi --version 2.0.0-preview3                
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest # if you are setting up this repo
dotnet tool install --local Microsoft.OpenApi.Hidi --version 2.0.0-preview3                
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Microsoft.OpenApi.Hidi&version=2.0.0-preview3&prerelease                
nuke :add-package Microsoft.OpenApi.Hidi --version 2.0.0-preview3                

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

Install Microsoft.OpenApi.Hidi 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 
• Show
 

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.
• --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

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.

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

Plugin

This command generates an OpenAI style Plugin manifest and minimal OpenAPI file based on the provided API Manifest

Examples:

1. hidi plugin -m exampleApiManifest.yml -o mypluginfolder 
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last updated
2.0.0-preview4 0 12/24/2024
2.0.0-preview3 78 12/20/2024
1.4.17 107 12/20/2024
1.4.16 2,933 11/12/2024 1.4.16 is deprecated because it has critical bugs.
1.4.15 355 11/7/2024 1.4.15 is deprecated because it has critical bugs.
1.4.14 1,672 10/29/2024
1.4.13 761 10/22/2024
1.4.12 958 10/14/2024
1.4.11 836 10/4/2024
1.4.10 739 9/30/2024
1.4.9 2,713 8/30/2024
1.4.8 564 8/23/2024
1.4.7 1,326 7/30/2024
1.4.6 1,463 6/27/2024
1.4.5 2,933 6/18/2024
1.4.4 2,069 5/28/2024
1.4.2 2,018 5/2/2024
1.4.1 2,178 4/5/2024
1.4.0 2,168 3/5/2024
1.3.10 346 3/4/2024
1.3.9 1,152 2/6/2024
1.3.8 494 1/29/2024
1.3.7 805 1/16/2024
1.3.6 2,917 11/22/2023
1.3.5 860 11/14/2023
1.3.4 495 11/7/2023
1.3.3 407 11/6/2023
1.3.2 805 10/30/2023
1.3.1 1,982 10/5/2023
1.3.0 896 9/26/2023
1.2.9 1,387 9/7/2023
1.2.8 677 9/5/2023
1.2.7 434 9/1/2023
1.2.6 2,992 7/24/2023
1.2.5 3,972 6/19/2023
1.2.5-preview3 2,248 5/3/2023
1.2.5-preview2 2,045 4/5/2023
1.2.5-preview1 837 3/30/2023
1.2.4 5,323 3/7/2023
1.2.3 807 2/28/2023
1.2.2 991 2/1/2023
1.2.1 419 1/31/2023
1.2.0 469 1/17/2023
1.1.0 1,121 11/21/2022
1.1.0-preview3 378 10/25/2022
1.1.0-preview2 363 10/6/2022
1.1.0-preview1 416 9/20/2022
1.0.0-preview9 544 7/19/2022
1.0.0-preview8 452 7/8/2022
1.0.0-preview7 414 7/6/2022
1.0.0-preview6 444 6/23/2022
1.0.0-preview5 416 6/8/2022
1.0.0-preview4 521 5/17/2022
1.0.0-preview3 310 5/16/2022
1.0.0-preview2 334 5/11/2022
1.0.0-preview10 357 9/19/2022
1.0.0-preview1 454 4/13/2022
0.5.0-preview6 357 4/10/2022
0.5.0-preview5 508 3/3/2022
0.5.0-preview4 340 2/8/2022