Page 1 of 1

Integrating REST API Reference (OpenAPI) with DITA

Posted: Wed Jun 05, 2019 6:42 pm
by hakeem_mvp
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!

Re: Integrating REST API Reference (OpenAPI) with DITA

Posted: Thu Jun 06, 2019 11:09 am
by Radu
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

Re: Integrating REST API Reference (OpenAPI) with DITA

Posted: Tue Aug 06, 2019 12:32 pm
by marcus_s
Hi Radu,
I'm not the original poster, but this seemed like a really interesting topic.

We are currently looking for a solution to present our REST API documentation. I just had the idea to use the responsive Webhelp for this as well and found this topic. Advantages would be having everything in one system (help and api reference) and we could use the Webhelp's search functionality and styling abilities.

I googled a bit and found this https://www.ibm.com/developerworks/libr ... index.html, but that's a solution for Java API.

For our REST Documentation we currently use yaml-files (json would be possible too) - the rendered result looks like this:
http://developer.cloud.intershop.com/?u ... %20-%20rma

The yaml-file can be found here:
https://ishswaggerui.blob.core.windows. ... agger.yaml

I could imagine DITA reference topics for each endpoint, including method, path, description, parameters, response codes, etc., grouped by topics named after the tags that the endpoints use (in the above case, "shop").

The conversion would be probably be relatively complex (I'm not really familiar with XSLT) and I also couldn't find any existing solutions, but maybe that would be a feature you could consider in the future?

Regards,
Marcus

Re: Integrating REST API Reference (OpenAPI) with DITA

Posted: Mon Aug 12, 2019 1:21 pm
by Radu
Hi Marcus,

Thanks for the details. I have a colleague interested in working on something like this, some kind of DITA Open Toolkit plugin which dynamically generates specific DITA content from Swagger JSON content referenced in the DITA Map.
If we make any progress on this I will update this forum thread.

Regards,
Radu

Re: Integrating REST API Reference (OpenAPI) with DITA

Posted: Thu Aug 22, 2019 3:41 pm
by marcus_s
That sounds great, thank you very much!

Re: Integrating REST API Reference (OpenAPI) with DITA

Posted: Wed Sep 18, 2019 4:03 pm
by marcus_s
For those who are interested in the feature, maybe this can help:
https://github.com/jason-fox/fox.jason. ... gh.swagger

I found this plugin a few weeks ago and tested it a bit.
Basically it works, but currently only under Linux and some Swagger specifications that appear to be valid according to Swagger editor throw error messages.

Maybe someone can use it as a basis for further development. :)