Integrating REST API Reference (OpenAPI) with DITA

hakeem_mvp
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

Greetings,

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!

Radu
Posts: 6340
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

Hi,

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:
https://github.com/oxygenxml/dita-excel

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?

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Post Reply