Machy.OpenApi.Tools.Core 1.0.0

OpenAPI Tools library

The .NET library allows you to:

• Load Open API document from file, URL, or any Stream in general
• List all endpoints (paths)
• Find the endpoints that match the search term
• List all schemas
• Find the schemas that match the search term
• Generate Markdown file(s) for endpoint(s)
• Generate Markdown file(s) for schema(s)
• Generate markmap file(s) from Markdown file(s)

Installation via NuGet

To install the client library via NuGet:

• Search for Machy.OpenApi.Tools.Core in the NuGet Library, or
• Type Install-Package Machy.OpenApi.Tools.Core into the Package Manager Console.

Prerequisities

• Required: Either .NET6 or .NET7 must be installed on your machine
• Optional: Install npm package markmap-cli npm install -g markmap-cli

OpenAPI Tools library

Load Open API document

Load the Open API document first. There are several ways to load Open API definition.

File

var tools = new OpenApiTools();
await tools.LoadDocumentFromFileAsync("path_to_yaml_or_json_file");

URL

Load Open API document from absolute URL:

var tools = new OpenApiTools();
await tools.LoadDocumentFromUrlAsync("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml")

Load Open API document from base address and relative URL:

var tools = new OpenApiTools();
await tools.LoadDocumentFromUrlAsync("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/", "master/examples/v3.0/petstore.yaml")

Stream

If you want to have more control, you can pass directly a stream which contains Open API definition. It's useful in case when the document is stored in a location which requires authentication to access the file, and neither LoadDocumentFromFileAsync nor LoadDocumentFromUrlAsync can be used.

var tools = new OpenApiTools();
await tools.LoadDocumentFromStreamAsync(stream);

Find paths

Once Open API document is loaded, you can search for paths.

Get all paths

List<string> paths = tools.GetPaths();

Find paths

List<string> paths = tools.FindPath("message");

Using regex

var allPaths = tools.FindPath(@"^(.*)");
var specificPaths = tools.FindPath(@"^(?=.*\bagreements\b)(?=.*\bfiles\b).*$");

Find schemas

In addition, you can search for schemas.

Get all schemas

List<string> schemas = tools.GetSchemas();

Find schemas

List<string> schemas = tools.FindSchema("security");

Using regex

var allSchemas = tools.FindSchema(@"^(.*)");
var specificSchemas = tools.FindSchema(@"^(?=.*\bmicrosoft\b)(?=.*\bsecurity\b).*$");

Generate Markdown files for endpoints

After the Open API document is loaded, you can generate Markdown files. When generating Markdown files for endpoints, specify the source paths and the output folder.

var allPaths = tools.GetPaths();
await tools.GenerateEndpointMarkdownFilesAsync(allPaths, @"C:\Temp\OpenApi\v1.0");

Generate Markdown files for schemas

When generating Markdown files for schemas, specify the source schemas and the output folder.

var allSchemas = tools.GetSchemas();
await tools.GenerateSchemaMarkdownFilesAsync(allSchemas, @"C:\Temp\OpenApi\v1.0");

Generate markmap files

To generate markmap files, specify the input folder and the output folder.

await tools.GenerateMarkmapFilesAsync(@"c:\Temp\OpenAPI\v1.0", @"c:\Temp\OpenAPI\v1.0");

It searches in the input folder and all its subfolders for .md files.

From each Markdown .md file, the markmap .html file is generated. The name of the .html file is the same as the name of source .md file.

Notes

Markmap files are generated by using npm package markmap-cli.

Close Open API document

To close the Open API document:

tools.CloseDocument();

It's useful when you want to open another Open API document. It will release all resources used by opened document.

Known issues

1. This tool is using the OpenAPI.NET SDK which doesn't release opened Open API document from the memory. Reported issue.

   When more Open API documents will be opened, the memory will be increasing.

2. It takes around 4 seconds to generate a markmap file by markmap-cli command. When generating markmap files for large Open API document, it can take around one hour to finish.

Recommendations

Additionally for Windows OS, to handle long path for generated Markdown or markmap files

set the value of the parameter HKLM\SYSTEM\CurrentControlSet\Control\FileSystem LongPathsEnabled to 1