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.