DocFxOpenApi 1.17.0

OpenAPI specification converter for DocFX

This tool converts existing OpenAPI specification files into the format compatible with DocFX (OpenAPI v2 JSON files). It allows DocFX to generate HTML pages from the OpenAPI specification. OpenAPI is also known as Swagger.

Usage

DocFxOpenApi -s <specs folder> [-o <output folder>] [-v]
  -s, --specfolder        Required. Folder containing the OpenAPI specification.
  -o, --outputfolder	Folder to write the resulting specifications in.
  -v, --verbose           Show verbose messages.
  --help                	  Display this help screen.
  --version              	Display version information.

The tool converts any *.json, *.yaml, *.yml file from the provided specification folder into the output folder. It supports JSON or YAML-format, OpenAPI v2 or v3 (including 3.0.1) format files.

If the -o or --outputfolder is not provided, the output folder is set to the input specs folder.

If normal return code of the tool is 0, but on error it returns 1.

Warnings, errors and verbose

If the tool encounters situations that might need some action, a warning is written to the output. The table of contents is still created.

If the tool encounters an error, an error message is written to the output. The table of contents will not be created. The tool will return error code 1.

If you want to trace what the tool is doing, use the -v or verbose flag to output all details of processing the files and folders and creating the table of contents.

Limitations and workarounds

• DocFX only supports generating documentation from OpenAPI v2 JSON files as of May 2021. Therefore the utility converts input files into that format.
• DocFX does not include type definitions as of May 2021.
• The OpenAPI v2 format does not allow providing multiple examples for result payloads. OpenAPI v3 allows providing either a single example or a collection of examples. If a collection of examples is provided, the utility uses the first example as an example in the output file.