From 5a3826cd02297560356d65f9056d924e6d4d4def Mon Sep 17 00:00:00 2001 From: Musale Martin Date: Thu, 13 Mar 2025 12:11:21 +0300 Subject: [PATCH] chore: update the readme for hidi examples and commands --- src/Microsoft.OpenApi.Hidi/readme.md | 112 ++++++++++++++++----------- 1 file changed, 67 insertions(+), 45 deletions(-) diff --git a/src/Microsoft.OpenApi.Hidi/readme.md b/src/Microsoft.OpenApi.Hidi/readme.md index 55986d14b..7a7667e02 100644 --- a/src/Microsoft.OpenApi.Hidi/readme.md +++ b/src/Microsoft.OpenApi.Hidi/readme.md @@ -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,9 +58,13 @@ 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 @@ -67,53 +72,70 @@ Used to convert file formats from JSON to YAML and vice versa and performs slici 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. \ No newline at end of file