Integrating REST API Reference (OpenAPI) with DITA

[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!

[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

[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

[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

[marcus_s]

That sounds great, thank you very much!

[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.

[Cosmin Duna]

Hi,

I just wanted to let you know that Oxygen 25.0 is out now and it contains support for integrating OpenAPI documentation Into DITA.
See this video demonstration for more information: https://www.oxygenxml.com/demo/integrat ... t_api.html

Best regards,
Cosmin

[Seema]

Hello,
I am not the original poster, but just had a query there in relation to this topic. I am trying to integrate generate Swagger API documentation (JSON format) in Oxygen Author and was able to create HTML output using the instructions in this video: https://www.oxygenxml.com/demo/integrat ... t_api.html. I also found this link https://www.oxygenxml.com/doc/versions/ ... or-x2.html and installed the OpenAPI Documentation Generator plugin. The plugin shows in my installed ad-ons, but I can't see the plugin in the Tools > Generate Documentation menu, as described in the documentation above. Do I need to do any additional settings to be able to see the plugin in the menu above.

Also, I wanted to know if it is possible to publish Swagger API documentation output in PDF format using OxygenAuthor? And if it is possible, is there any help article available on how to achieve this?
Thanks,
Seema

[Cosmin Duna]

Hi,
Did you publish the DITA Map containing a topic reference to the Swagger/OpenAPI documentation to WebHelp?
You can also publish this DITA Map to PDF using the "DITA Map PDF - based on HTML5 & CSS" transformation scenario:

image.png

We also have a webinar where the integration of OpenAPI into DITA documentation is presented: https://www.oxygenxml.com/events/2022/w ... rmats.html

You can also convert the OpenAPI document to a DITA Map using the Batch Documents Converter add-on:
https://www.oxygenxml.com/doc/ug-editor ... addon.html
And after this, you can publish the resulting DITA Map using the same transformation scenario (DITA Map PDF - based on HTML5 & CSS).

About the OpenAPI Documentation Generator plugin, you should be able to see the "OpenAPI Documentation..." action in the "Generate Documentation" sub-menu after the installation. Could you open the "Plugin" preferences page ( by invoking the "Preferences.." action from the "Options" menu) and check if the "OpenAPI Documentation Generator" plugin is enabled in the table from this page?

Best regards,
Cosmin

[Seema]

Hello,
Thanks, yes, the DITA Map containing a topic reference to the Swagger/OpenAPI documentation was published using the WebHelp Responsive scenario. The ditamap we used had some html-specific settings, we fixed that last week to include common settings and can now publish output in PDF format.
Regarding the OpenAPI Documentation Generator - I have the plugin enabled on the preferences page, but it doesn't show in the "Generate Documentation" sub-menu. However, I noticed that the plugin installed fine on Oxygen XML Editor but not in Oxygen XML Author. Is it that the plugin is available only for Oxygen XML Editor and not for Author? I'm generating all my API documentation using Oxygen Author.
Thank you for your assistance,
Seema

[Cosmin Duna]

Hi Seema,
Unfortunately, this add-on is only available on Oxygen XML Editor and Developer. Also, the OpenAPI editing support is not available on Oxygen XML Author.
The dynamic converter is present in all products because it's part of the DITA publishing support.

Best regards,
Cosmin

[Seema]

Hi Cosmin,
Thanks for clarifying.
Regards,
Seema

[Seema]

Hello,
Just a follow-up question on integrating Swagger documents with our regular docs.
We are currently using the dynamic OpenAPI to DITA converter to publish our Swagger API documentation. I just wanted to know is it possible to generate interactive Swagger documentation (for example, like the one here: https://developer.amazon.com/docs/app-s ... eListing_1) using the OpenAPI to DITA converter?
I have watched the demo links that were posted on this thread:
https://www.oxygenxml.com/events/2022/w ... rmats.html
https://www.oxygenxml.com/demo/integrat ... t_api.html
but just wanted to know if it was possible to generate interactive Swagger docs using Oxygen Author, and if you could point me to any demos or documentation regarding this in case it is available.
Thank you,
Seema

[Cosmin Duna]

Hi Seema,

Thank you for reaching out to us. Unfortunately, it is not currently possible to obtain documentation where you can test the REST API when publishing a DITA Map that contains Swagger documentation.
We already have an internal issue for embedding an API explorer in the WebHelp content generated from OpenAPI (Swagger). Additionally, I have added your request to this issue to help prioritize its resolution.

For now, you can only test your API in the Swagger editor from Oxygen using this add-on: https://www.oxygenxml.com/doc/versions/ ... ester.html

Best regards,
Cosmin

[marcus_s]

Since the Oxygen Open API features have been available for a while, are there any Oxygen-generated REST API docs out in the wild you can think of? I've started working on a new project and could need some inspiration for styling.

Especially with more complex schemas, it is sometimes very hard to grasp because the indentations look rather confusing; perhaps separating lines or tables would be helpful in some places. Here's an example to show you what I mean. It's created with the Oxygen default template from the Swagger Petstore sample API (https://petstore.swagger.io/):

image.png

[Radu]

Hi Marcus,
In general as an enterprise tool and for security reasons we do not disclose publicly web sites using our WebHelp Responsive output.
About the Rest API to DITA conversion, we have not received that much feedback after it was created so it's possible it's not used that much.
From what I remember we tried to add enough @class attribute values in the HTML output so that an extra CSS customization could be used to improve on the layout.
I will add an internal issue based on your feedback and in the meantime maybe you can attempt to create your own CSS customization for the REST API based output.

Regards,
Radu

[marcus_s]

Hi Radu,
Okay, that's understandable, but thanks for the quick response and for sharing your feedback.

I also noticed that code examples are missing in the output, for example for response and request bodies. Maybe you could add that to the feedback as well. Thanks!

Regards,
Marcus

[Radu]

Hi Marcus,
Right, we have an internal issue for this and we'll update this forum thread if we manage to add this improvement in a future Oxygen version.
Pasting the internal issue ID below for future reference:

EXM-50193 Generate codeblock samples in Open API conversion result

Regards,
Radu