VideosIntegrating REST-API Content Into DITA Documentation in Oxygen

Overview

Duration: 06:41

The purpose of this video is to demonstrate how you can integrate REST-API content that is documented using the OpenAPI standard into your DITA documentation using some Oxygen tools and features.

Transcript

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.

Use Oxygen Feedback to ask us anything about this video.

Products

Features

Shop

Resources

Support

Company

© 2002-2024 SyncRO Soft SRL. All rights reserved.

This website was created & generated with <oXygen/>®XML Editor