00:00:05The purpose of this video is to demonstrate ways
that you can integrate REST-API content that is in
00:00:11OpenAPI format into DITA documentation using some
of Oxygen's tools and features. In the first part,
00:00:18I'll demonstrate converting OpenAPI documents
to DITA during the publishing stage.
00:00:24So, I have a sample DITA map open,
and in the DITA Maps Manager,
00:00:29I'll right-click the root map, go to
Append Child, and select "Reference"
00:00:35because I want to add a reference to a sample
OpenAPI document that I've prepared.
00:00:41In the resulting dialog box, I need to change
the file type to "DITA Compatible Files".
00:00:48And now my OpenAPI document appears in
the middle pane so I'll select it.
00:00:53And in the Attributes tab...
notice that Oxygen detected the
00:00:58selected file as an OpenAPI format and
automatically set the conversion format
00:01:03for the reference to openapi-to-dita.
Now I'll go back to the Target tab.
00:01:11I'll click on the ID drop-down to show you
that you can insert a reference to a particular
00:01:16operation from your RestAPI ...
but I'll select the Composite root
00:01:22to reference the whole document ...
and I'll click Insert and Close...
00:01:30and notice that the reference
was inserted into my map.
00:01:34Now I'll click the Configure Transformation
Scenarios button in the DITA Maps Manager,
00:01:40I'll select the "DITA Map WebHelp
Responsive" scenario, and I'll apply it.
00:01:46And in the resulting WebHelp output, I'll
open the document I just referenced to show
00:01:52you that it was dynamically converted to
DITA content during the transformation.
00:01:58Next, I'll demonstrate adding references
to operations from OpenAPI documents.
00:02:05I'll open one of my sample files...
00:02:08and I want to insert a cross reference
at the end of this paragraph.
00:02:13So, I'll right-click, go to the Link
submenu, and select Cross Reference.
00:02:20I'll click the browsing button to
locate my target OpenAPI file.
00:02:25In this dialog box, I need to change the
file type to "DITA Compatible Files",
00:02:30and now my OpenAPI document
appears, so I'll select it.
00:02:36Note that the content of the OpenAPI document
is converted to DITA in the background so it
00:02:41allows me to insert references the
same as with any DITA content.
00:02:46I'll use the filter field to quickly locate
the target element I want to reference,
00:02:51and I'll click Insert and Close.
Notice that the cross reference was
00:02:57inserted in the document and in the Attributes
view, notice that the format was automatically
00:03:02set as openapi-to-dita.
Now I'll open another sample
00:03:07file and insert a reference to reused content.
I'll put the cursor in an appropriate location.
00:03:14I'll right-click, go the the Reuse
submenu, and I'll select Reuse Content.
00:03:21Similar to the previous dialog box,
I'll click the browsing button...
00:03:25and I'll make sure the file type is "DITA
Compatible Files", and select the OpenAPI file.
00:03:33Again, the content of the OpenAPI document was
automatically converted to DITA in the background
00:03:39so I can insert a reference to reused content.
I'll narrow the list of targets...
00:03:46and I'll select the target element
and click Insert and Close...
00:03:51and you can see that the reference to the
reused content was inserted in the document.
00:03:57I'll apply the same transformation
scenario as I did before.
00:04:02In the resulting WebHelp output, I'll open the
documents where I just added the references.
00:04:07In the Benefits topic, you can see that the
cross reference link is there and it works.
00:04:16And in the Accessing Data topic, you can see
that the referenced reused content is there.
00:04:23In the next part, I'll quickly show you
00:04:25some features for validating
OpenAPI documents as DITA.
00:04:30I'll open one of the sample topics and
I'll go to the Text editing mode...
00:04:34and I'll intentionally break a reference
to create a validation error...
00:04:40you can see that the error message
indicates that the reference isn't found.
00:04:46I can also use the "Validate and
Check for Completeness" feature from
00:04:50the DITA Maps Manager.
I'll click "Check"...
00:04:55and any OpenAPI documents that
are referenced in the map are
00:04:59converted to DITA topics in the background and
validated the same as any other DITA topic.
00:05:05You see that there are some errors listed in
the Results pane due to the reference I broke,
00:05:10including an error detected
for the OpenAPI document.
00:05:16For the last part of the demonstration, I'll show
you that if you want to work directly with DITA,
00:05:21you can use Oxygen's Batch Documents
Converter add-on to convert OpenAPI
00:05:26files into DITA topics or into DITA maps
with separate, referenced topics.
00:05:32In the DITA Maps Manager, I'll right-click
the root map, I'll go to Append Child,
00:05:38then the Import submenu, and
I'll select OpenAPI to DITA.
00:05:45In the resulting dialog box, I'll click Add
Files, and I'll select my OpenAPI document.
00:05:54I need to deselect the "Open
the converted file" option.
00:05:58And I need to enable the "Create DITA
map from OpenAPI documents" option.
00:06:05Then I'll click Import.
00:06:10Notice that it added a reference to
a new DITA map and it automatically
00:06:14created separate DITA topics for
each of the OpenAPI objects.
00:06:19And I'll open one of them to
show you what it looks like.
00:06:25That concludes the demonstration
about intregrating REST-API content
00:06:29in OpenAPI format into DITA. As
always, thanks for watching and
00:06:34we invite you to please subscribe to
our various social media channels.