Edit online

Generating OpenAPI Documentation

Oxygen XML Developer includes a tool for generating documentation for OpenAPI 3.0, or 3.1 documents in either JSON or YAML format, including annotations and cross references. The documentation displays information about the servers, paths, components and tags defined in the OpenAPI documents and you can choose whether the output is presented in HTML (with various sections, hyperlinks, and filtering options), DITA, or PDF.

Quick Installation

You can drag the following Install button and drop it into the main editor in Oxygen to quickly initiate the installation process:

Install

Manual Installation

To manually install it the add-on, follow these instructions:
  1. Go to Help > Install new add-ons to open an add-on selection dialog box.
  2. Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the Show add-ons from field or select it from the drop-down menu.
    Note: If you have issues connecting to the default update site, you can download the add-on package, unzip it, then use the Browse for local files action in the Install new add-ons dialog box to locate the downloaded addon.xml file.
  3. Select the OpenAPI Documentation Generator add-on and click Next.
  4. Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
  5. Restart the application.

Result: The OpenAPI Documentation dialog box is now available and can be selected from the Tools > Generate Documentation menu.

Generating OpenAPI Documentation

To generate OpenAPI documentation, select OpenAPI Documentation from the Tools > Generate Documentation menu. This opens a dialog box where you can specify the location of the OpenAPI file and the output file, as well as the type of output to generate.

This tool requires an additional add-on to be installed, so the first time you invoke the action, Oxygen XML Developer presents a dialog box asking if you want to install it. Once installed, you need to restart Oxygen XML Developer and the OpenAPI Documentation action will invoke the tool.

Figure 1. OpenAPI Documentation Dialog Box
The OpenAPI Documentation dialog box includes the following fields and options:
OpenAPI URL
The URL of the OpenAPI file (it can be in either JSON or YAML format). You can specify the path by using the text field or the browsing button ().
Output file
The path to the folder where the generated file(s) will be saved.
Generate HTML output
Choose this option to generate the output in HTML format.
Split output into multiple files
If selected, the application splits the output into multiple files. You can choose between splitting them by component name or location.
Included JSON schema component details
This section can be used to specify whether or not details about the following components that belong to internal or imported schemas are shown in the generated documentation:
  • Annotations - Displays the annotations (title, description) for each component (property or definition).
  • Constraints - Displays the schema constraints for each component, according to its type.
  • Source - Displays the text schema source for each component.
  • Location - Displays the schema location for each component.
  • Used By - Displays the list of all the components that reference the current definition.
  • Properties - Displays the properties of an Object Schema.
  • Pattern Properties - Displays the patternProperties of an Object Schema.
  • Enumerations - Displays the enumerated values, if specified in the schema.
  • Diagram - Displays the diagram image for each component. The diagrams are generated according to the options specified in the Schema Design preferences page. Diagrams are also generated for components within schemas from referenced files.
  • Composition - Displays the oneOf, anyOf, and allOf compositors that are used for combining schemas.
Generate DITA output
Choose this option to generate the output in DITA format.
Create DITA map from OpenAPI document
If selected, the application generates a DITA map with referenced topics based on the input OpenAPI document.
Generate PDF output
Choose this option to generate the output in PDF format.

Click the Generate button to generate the OpenAPI documentation.

Generated OpenAPI Documentation in HTML Format

When generating the OpenAPI documentation in HTML format, it is presented in the browser with various sections, hyperlinks, and options.

Figure 2. OpenAPI Documentation Example

The generated documentation includes a Table of Contents on the left pane with links to particular sections in the right pane. You can collapse or expand details by using the Collapse or Expand buttons.

Resources

For more information about OpenAPI editing, testing, and documenting, watch the following webinar: