VideosOpenAPI Document Editing in Oxygen XML Editor


Duration: 05:24

This video shows some of the editing features that are available in Oxygen when working with OpenAPI documents.


00:00:06The purpose of this video is to  demonstrate some of the editing  
00:00:10features that are available in Oxygen  when working with OpenAPI documents.  
00:00:15OpenAPI is a format for describing and documenting  APIs. Oxygen provides built-in frameworks for  
00:00:22OpenAPI documents and supports versions 2.0,  3.0, and 3.1. Some of the features include  
00:00:29automatic validation, content completion,  and editing in the Text or Author modes.  
00:00:36I'll start by creating a new OpenAPI document  using the file wizard. Notice that there's  
00:00:42several different versions to choose from.  I'll create a version 3.1 JSON file.  
00:00:54Oxygen automatically recognizes OpenAPI  documents and validates them according to  
00:01:00the specification for that version. You can  see that my template file was successfully  
00:01:05validated against an OpenAPI 3.1 schema. You can use the Outline view to navigate  
00:01:12and visualize the structure of the document.  This document contains some required fields:  
00:01:17"openapi" indicates the version of the  OpenAPI Specification, "info" provides  
00:01:24metadata about the API, and "paths" specifies the  available paths and operations for the API.  
00:01:31Then there are also additional optional  fields: "tags", "servers", and "components". 
00:01:38Next, I'll show you the content completion  feature that provides smart completion  
00:01:42proposals based on the current context. It  lists the valid properties and values that  
00:01:48can be inserted at the particular location.  Notice that each proposal has a tooltip that  
00:01:53presents the documentation for the particular  property collected from the associated schema.  
00:01:59I'll go ahead and add a new server location  in the API, with a description and url. 
00:02:09Now I'll continue to show you the content  completion and other editing features by  
00:02:13working with a more complex OpenAPI document.  This particular sample is an API document for  
00:02:19a Pet store. Notice that Oxygen automatically  detects that it is an OpenAPI 3.0 document.  
00:02:25Hence it will use the corresponding OpenAPI 3.0  schema for validation and content completion.  
00:02:32To further demonstrate the features, I'll  add a delete operation in a particular path.  
00:02:38I'll use the search filter in the  Outline view to find the "/pet" path.  
00:02:44Then in the editor, I'll scroll down to  the location where I want to added the  
00:02:48delete operation. So, after the ending  curly bracket for the "post" object,  
00:02:53I'll type a comma and press Enter  to invoke the content completion,  
00:02:58I'll select the "delete" operation, it  automatically added "responses" for me,  
00:03:04I'll type "400" for the number of responses  and then I'll add a description ...  
00:03:13Then I'll add "parameters". Notice  that the required properties for it  
00:03:18are automatically inserted ... I'll  continue to fill in the values ...  
00:03:31Then I'll specify the "schema" for the  parameters ... and the "type" ... and  
00:03:38complete the structure. Next, I'll find a reference  
00:03:42within the document ... because I want to  show you that I can hold down the Ctrl key  
00:03:48on my keyboard and click the reference with my  mouse to navigate to the reference location.  
00:03:53I'll do it again, and note that this one was  a reference to a separate schema file, which  
00:03:58is automatically opened in Oxygen's specialized  Design mode ... where you can work with the schema  
00:04:04in a visual diagram type of mode that makes it  very easy to visualize and edit the schema.  
00:04:10Next, I'll go back to my OpenAPI document to show  you that Oxygen also provides specific rendering  
00:04:16for OpenAPI documents in the visual Author  editing mode. This mode offers an alternative to  
00:04:22the text-based editing mode making it easier  to visualize the OpenAPI documentation.  
00:04:28It offers access to some form controls, such  as a drop-down for selecting the version ...  
00:04:34of course I can add content  in appropriate locations ...  
00:04:40it has expandable and collapsible sections ...  content completion ... as well as other visual  
00:04:48editing features that are available  in the Author visual editing mode.  
00:04:54Oxygen also provides a tool  for generating documentation  
00:04:57for OpenAPI documents and for testing the  API using a specialized OpenAPI tester.  
00:05:04Please see our user guide topics for more  information on these tools. This concludes the  
00:05:10demonstration about the OpenAPI editing features  in Oxygen.
00:05:14As always, thank you for watching and we invite you to please  subscribe to our various social media channels.

Use Oxygen Feedback to ask us anything about this video.