OpenAPI.NET CLI tool for slicing OpenAPI documents
Install
No framework information available.
README
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 from NuGet. Hidi 2.x is maintained on this repository's support/v2 branch and requires .NET 8.
.NET CLI(Global)
dotnet tool install --global Microsoft.OpenApi.Hidi --version 2.12.2
.NET CLI(local)
dotnet new tool-manifest # if the repository does not have a tool manifest
dotnet tool install --local Microsoft.OpenApi.Hidi --version 2.12.2
Build and install from this repository
Run these commands from the repository root with the .NET 10 SDK and .NET 8 runtime installed:
dotnet pack src\Microsoft.OpenApi.Hidi\Microsoft.OpenApi.Hidi.csproj -c Release -o artifacts\hidi\nuget
.\install-tool.ps1
artifacts\hidi\installed\hidi --help
Hidi uses published Microsoft.OpenApi and Microsoft.OpenApi.YamlReader packages,
and builds the OData converter from this repository. No sibling source checkout
is required. Its version is independent of the OData library version.
The local NuGet configuration excludes remote feeds so this smoke test installs
the newly built artifact, not the already-published package with the same version.
Windows executable
dotnet publish src\Microsoft.OpenApi.Hidi\Microsoft.OpenApi.Hidi.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:PackAsTool=false -p:GeneratePackageOnBuild=false -o artifacts\hidi\win-x64
artifacts\hidi\win-x64\Microsoft.OpenApi.Hidi.exe --help
CI produces a Windows executable artifact without publishing a production release.
Docker
docker build --tag hidi:local .
docker run --rm hidi:local --help
Mount input files and a writable output directory when transforming documents:
docker run --rm --mount "type=bind,source=$PWD\test\Microsoft.OpenApi.Hidi.Tests\UtilityFiles\SampleOpenApi.yml,target=/app/openapi.yml,readonly" --mount "type=bind,source=$PWD\artifacts\hidi,target=/app/output" hidi:local transform --openapi /app/openapi.yml --output /app/output/result.json --format json
Local/CI builds use the public-only strong-name identity. Official release
artifacts are signed in Azure Pipelines; private signing keys do not belong in
this repository. The migration baseline 2.12.2 is already published.
hidiPublishingEnabled is the string 'true' in the release configuration:
after merging, successful hidi-v2.* tag builds can enter the protected NuGet,
executable, and Docker publishing stage. Hold the enablement merge until official
signed-package verification and coordinated cutover approval. Source support/v2
publisher cleanup is already accepted in
microsoft/OpenAPI.NET#3109;
source-main cleanup is not a prerequisite for this branch. Branch/PR builds
remain build-only. This change does not publish artifacts or grant permissions.
Official tool packing passes HidiSignedAssemblyPath to replace the Hidi DLL
in the SDK's ResolvedFileToPublish items after ComputeFilesToPublish.
PackAsTool publishes the intermediate assembly from obj, so replacing only
the DLL in bin does not preserve its Authenticode signature. The opt-in target
uses the exact ESRP staging DLL without recompiling it; ordinary local packing
and Windows single-file publishing retain their default inputs.
Before NuGet signing, scripts/verify-hidi-package-assembly.ps1 requires exactly
one DLL at tools/net8.0/any/Microsoft.OpenApi.Hidi.dll, verifies its SHA256
matches the staging DLL, and requires valid Microsoft Corporation Authenticode
signatures on both. Missing, mismatched, unsigned, or unverifiable payloads fail
the build. A signed NuGet container alone is not assembly-signature evidence.
Local byte-provenance checks and mocked signature unit tests cannot establish
Microsoft ESRP signing readiness; that requires a publish-disabled official run
after the normally approved merge.
The standard Release Please config tracks Hidi as its own component, with a
separate manifest version, project version, changelog, and hidi-v2.* tags.
The first destination package release must advance beyond the baseline and use
an exact hidi-v2.<version> tag matching the project. OData releases use separate
artifacts and tags. Existing hidi-v2.13.0 points at an earlier publish-disabled
revision without the signed-package fix. Never move or reuse that tag, rerun it
to publish, or republish its old unsigned artifacts. Future publication requires
a new corrected release ref/version after the cutover hold clears.
Docker builds opt into HidiPublicSignBuild=true for the local OData project,
using its own public-only key without changing normal OData signing behavior.
Private .snk resources are excluded from the Docker context.
The official pipeline stages a separate HidiDockerContext pipeline artifact
in the build job. It contains only the hidi and OData reader sources, required
build and Docker files, and the two public-only signing keys; build outputs and
private keys are excluded. The container release job consumes this artifact as
a 1ES input without checking out the repository. NuGet and Windows release
artifacts continue to use the separate Hidi artifact.
The container release job retains the existing docker-images-deploy
environment and its approvals/checks. The destination pipeline must be authorized
for that protected environment before official publishing can execute. Signed
artifact verification does not prove live NuGet or Docker publishing permissions,
and neither the flag nor this change bypasses release approvals/checks.
The official container job authenticates to the approved
GraphDeveloperExperiences_Public central feed using the existing Azure DevOps
job identity. A credential-bearing NuGet config is created with owner-only
permissions in the agent temp directory, passed as the BuildKit nuget_config
secret, and removed in finally, including on build failure. It is never staged
in HidiDockerContext, published as an artifact, or copied into an image layer.
The destination pipeline identity must already be authorized to read the feed;
this handoff does not grant permissions or bypass service-connection approvals.
The Dockerfile secret mount is optional, so local and GitHub Actions builds
without a secret continue to use their default NuGet sources.
The gated official pipeline retains the consumer image
mcr.microsoft.com/openapi/hidi, backed by
msgraphprodregistry.azurecr.io/public/openapi/hidi. Stable images use latest
and the independent hidi version, for linux/amd64 and linux/arm64/v8.
No image is pushed during this migration. Privileged cross-platform emulation
setup belongs only in the authorized CI pipeline, not a shared local environment.
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 validate --openapi C:\OpenApidocs\Mail.yml --loglevel trace`
Run
hidi validate -hto 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
• --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:
- Filtering by OperationIds
hidi transform -d files\People.yml -f yaml -o files\People.yml -v 3.0 --op users_UpdateInsights --co
- Filtering by Postman collection
hidi transform --openapi files\People.yml --format yaml --output files\People2.yml --version 3.0 --filter-by-collection Graph-Collection-0017059134807617005.postman_collection.json
- CSDL--->OpenAPI conversion and filtering
hidi transform --csdl Files/Todo.xml --output Files/Todo-subset.yml --format yaml --version 3.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 -hto 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:
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:
hidi plugin -m exampleApiManifest.yml -o mypluginfolder
Run
hidi plugin -hto see all the available usage options.
Changes from Previous Version
Adoption Assessment
A verified publisher signal is available. Assess fit from the package's supported frameworks, license and dependency graph rather than popularity alone.
Related Guides & Workflows
Learn how to evaluate, integrate, or audit this package in your .NET project.