Edit online

OpenAPI (Swagger) Document Type (Framework)

OpenAPI specification, previously known as Swagger specification, is a specification that defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. Use cases for machine-readable API definition documents include interactive documentation, code generation for documentation, automation of test cases, and more. OpenAPI documents describe an API's services and are represented in either YAML or JSON format.

Oxygen XML Editor includes three OpenAPI frameworks:
  • OpenAPI 2.0
  • OpenAPI 3.0
  • OpenAPI 3.1

Editing OpenAPI Documents

You can edit OpenAPI files in Text mode and you have access to all the usual text editing actions and you can also edit them in the visual Author editing mode and you have access to the various features and actions that are available when editing XML documents in Author mode.

When opening a detected OpenAPI document in Author mode, you have access to some form controls, collapsible sections, descriptions can be edited inline in a text area that features syntax highlighting, and other features to help you visualize and edit these documents. Also, when editing OpenAPI files in Author mode, a + Markdown Syntax Highlight CSS style can be selected from the Styles drop-down menu (available on the toolbar) to visualize descriptions with Markdown style syntax highlights.

Tip: There is an OpenAPI sample document named petsore.json located in [OXYGEN-INSTALL-DIR]/samples/json/openapi that you can use to see how these documents are rendered in Oxygen XML Editor.

Validation and Content Completion

Validation and content completion is supported in Oxygen XML Editor for OpenAPI documents (version 2.0, 3.0, 3.1). The validation and content completion in OpenAPI documents are driven by schemas according to the OpenAPI version in the document. Each of the three frameworks (OpenAPI 2.0, OpenAPI 3.0, and OpenAPI 3.1) have a unique schema specified for content completion and validation. When opening an OpenAPI document (in JSON or YAML format), Oxygen XML Editor automatically associates the corresponding schema based on the OpenAPI version of the document.

Resources