Integrating REST API Reference (OpenAPI) with DITA

Posts: 1
Joined: Wed Jun 05, 2019 6:26 pm

Integrating REST API Reference (OpenAPI) with DITA

Post by hakeem_mvp » Wed Jun 05, 2019 6:42 pm


I typically create user docs in DITA, but I'm working on a REST API project where all of the reference content is written in JSON (it's an OpenAPI/Swagger specification to be exact).

I know Oxygen supports JSON, but I'm still unsure how to approach this. Can I publish a DITA map that includes a JSON file? Do I need to convert the JSON to XML?

There seem to be a lot unknowns, and I don't want to end up down the wrong path. Any tips or lessons learned from people who have done something like this are much appreciated!

Posts: 6329
Joined: Fri Jul 09, 2004 5:18 pm

Re: Integrating REST API Reference (OpenAPI) with DITA

Post by Radu » Thu Jun 06, 2019 11:09 am


You have quite an interesting use case. The DITA Open Toolkit allows adding plugins, plugins which would pre-process referenced JSON files to DITA.
For example if in a topicref in the DITA Map you would refer to a JSON file:

Code: Select all

<topicref href="test.json" format="json"/>
a DITA Open Toolkit plugin could dynamically convert the JSON file to DITA when publishing.
At some point I created a similar plugin for referring to Excel documents in DITA Maps:

Can you give me an example of how the JSON looks like and how the equivalent DITA topic obtained from the JSON file should look like?

Radu Coravu
<oXygen/> XML Editor

Post Reply