OpenAPI
OpenAPI Editor
OpenAPI is a community-driven open specification that defines a language-agnostic interface used to describe, produce, consume, and visualize RESTful APIs and web services. It 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 the API (or its elements) and are represented in either YAML or JSON formats.
OpenAPI documents can of course be edited in the Oxygen Text mode, but a built-in framework also renders OpenAPI (Swagger) documents in the Author visual editing mode. The framework is an extension of the JSON framework. When opening a detected OpenAPI document in Author mode, you have access to some form controls, collapsible sections, and other features that help you to visualize and edit these documents.
OpenAPI Tester Tool
Oxygen includes a GUI interface testing tool for OpenAPI files. The tool provides the ability to execute API requests and validate responses on the fly to ensure that they work as expected. It can be used for OpenAPI files in JSON or YAML format. The tool is available in the Tools->JSON Tools menu. It requires an add-on to be installed but you have the option to automatically install it the first time you select the tool.
Using the Run OpenAPI Test Scenario tool you can run a set of OpenAPI test scenarios.Oxygen also includes a specialized framework for editing and creating OpenAPI test scenario files. It includes the usual text editing actions, a visual editing interface, content completion, and automatic validation.
OpenAPI Documentation Generator
Oxygen includes an OpenAPI Documentation generator tool that helps you to easily generate full documentation for OpenAPI components in HTML format, including comprehensive annotations and cross references. The documentation displays information about the servers, paths, components and tags defined in the OpenAPI documents. It also includes the JSON schema documentation for the components along with the diagram image for each component generated according to specified options. You can select which components are shown in your output after the OpenAPI documentation is generated.
The generated documentation includes a Table of Contents on the left pane with links to particular sections in the right pane. You can collapse or expand details by using the Collapse or Expand buttons. The tool is available in the Tools->Generate Documentation menu. It requires an add-on to be installed but you have the option to automatically install it the first time you select the tool.
OpenAPI Documentation Examples
Documentation for 1Password Connect API
- Generate documentation in one file - 1Password-OpenAPI-Specification-Standard
- Generate documentation split by components - 1Password-OpenAPI-Specification-Split-Components
- Generate documentation split by location - 1Password-OpenAPI-Specification-Split-Location
Documentation for Swagger Petstore Extended
- Generate documentation in one file - Petstore-OpenAPI-Specification-Standard
- Generate documentation split by components - Petstore-OpenAPI-Specification-Split-Components
- Generate documentation split by location - Petstore-OpenAPI-Specification-Split-Location