Converting OpenAPI to DITA XML and Publishing to WebHelp (Experimental)

OpenAPI documentation is usually stored in JSON or YAML formats. In this topic, we will attempt to convert OpenAPI documentation to Markdown using widdershins, convert Markdown to DITA content using the Oxygen Batch Converter add-on, and then publish to WebHelp Responsive output.

1. Download the Yaml or JSON representation of an OpenAPI specification to the local disk. For this example, I used the OpenAPI documentation from the Oxygen Content Fusion server: https://fusion.oxygenxml.com/api/swagger.json.
2. Download and install widdershins.
3. From a command prompt or terminal, produce a Markdown representation of the original API file:

   widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --summary /../swagger.json -o swagger.md

4. In the Oxygen application, use the Tools > Batch Documents Converter > > Markdown to DITA conversion to convert the Markdown file to a DITA Map.

   

5. Once you have the DITA Map, you can publish it to WebHelp Responsive or integrate it as part of a larger DITA Map. The map can be further modified by adding chunking attributes to avoid breaking the published output in too many HTML files.
6. When publishing the swagger.ditamap to WebHelp, we set the validate parameter to no because the produced DITA content had some invalid content inside.
7. The resulting WebHelp output is available here: https://blog.oxygenxml.com/resources/open-api-webhelp/returns_the_current_user%27s_details.html. Codeblocks that contain sample source code are divided into multiple tabs using this plugin: Show Consecutive DITA Code Blocks in Separate Tabs.