Introduction
Introduction
The Designer section of the Platform can be accessed from the main menu and provides functionality for creating and editing OpenAPI specifications of REST APIs. This section is designed to be easily used by users with different levels of experience and expertise for generating OpenAPI specifications.
Accessing the API Designer
Preconditions
Available to all user types except Visitor, unless the administrator has disabled it for a type of user in Profiling.
Steps
Navigate to
Designerfrom the main menu, or click Go to Designer in the technical details of an API Product to open its back-end OpenAPI definition.
Post-conditions
The user can view, create, modify, validate, test and save an OpenAPI specification.
Upload an OpenAPI specification file from local storage
Steps
Click the Options button located at the top right of the Designer panel.
Select the “Load new OpenAPI definition” option.
In the window, click “Browse file” to select a file from your local machine among the supported formats (max 10 MB). Then click load.
Post-conditions
A notification will be displayed indicating the outcome of the operation. If the upload is successful, all the data will be available in the form when using Form View, or the full JSON/YAML content will be visible in Code View.
Tips
In this case, no validation of the specification is performed, except for checks on the file extension and file size. You may validate the uploaded specification by clicking the “Validate” button at the bottom.
Load an OpenAPI specification file using a template
Steps
Click the Options button located at the top right of the Designer panel.
Select the “Load template” option.
In the window, you can choose a template from a preloaded set in the drop-down menu, then click Load.
Post-conditions
The template will always be loaded successfully, and it will replace the previously edited specification. Make sure you downloaded any open specifications with unsaved changes before performing this action.
Tips
In this case, no validation of the specification is performed. You may validate the uploaded specification by clicking the “Validate” button at the bottom.
Edit an OpenAPI specification file
Steps (from Form View)
From the Form View, it is possible to select the different sections through the side menu and then operate on the individual fields. The sections are the same as those expected by the specification, which are Info, Tags, Servers, Paths, Security, and Components.
Within these sections, the form view allows users to edit all the possible fields of the specification, according to the OpenAPI specification schema, with dedicated and dynamic form fields.
For example users can add a new path and method to the specification by:
Going to the path section.
Clicking Add and naming the path of the endpoint.
Opening the path and adding a summary and a description, as well as any necessary header or query parameters via the dedicated subsections.
Creating a method for that path through the “+ Method” button.
Switching tab to the method and editing the method’s Parameters, Requests, and Responses via the dedicated sub-tab. The details of Parameters, Requests, and Responses can be defined locally for each method, or globally from the Components section where they can be referenced across different endpoints and methods.
The Components section provides dedicated subsections for the specification of global and reusable elements such as: Examples, Headers, Parameters, Request Bodies, Responses, Security Schemas, and especially Schemas, where users should define the global and reusable data structures.
For example, to create a schema with the schema builder, which can be reused in many Requests or Responses, users can:
Go to the Components section and enter the Schemas sub-section.
Click “+ Add” to add a new schema.
In the dedicated window generated below the user can structure the schema by using either a Tree View, or by using the embedded Code View, which lets the user edit the schema’s JSON or YAML directly.
Using the Tree View, which displays the schema in a visual way on the left panel, while showing each property’s metadata on the right panel, the user can add sub-properties with the “+” button or more specific of sub-properties via the options button beside it.
The user can then define for each property all of its metadata on the right panel, such as type (String, Number, Boolean, etc.), cardinality, validation rules, default values, and examples.
Steps (from Code View)
In the Code View, it is possible to intervene directly by editing the content fully in the editing panel via a code editor, choosing between JSON or YAML format.
Post-conditions
Depending on which view you are working in, the other view will be updated in real time as well.
Tips
If fields or parameters are added in Code View that are not syntactically valid (and therefore cannot be interpreted in Form View), they will be removed once you switch views, except for those classified as extensions (x-). Make sure any edits made in code view are syntactically valid before switching back to the Form View.
When you leave the Designer with unsaved changes, the Platform asks for confirmation.
Linting
Preconditions
Having clicked the “Validate” button in the bottom and having errors and/or warnings and/or messages.
Steps
In the Lint button, located at the top right of the Designer panel, any errors, warnings, or messages detected in the OpenAPI definition are displayed. These may result from non-compliance with the OpenAPI specification standard or from internal governance rules.
By clicking the Lint button, the panel containing the detected issues is opened.
At the top of the panel, the different types of detected issues are represented by icons with their respective counters. Clicking on each icon displays the corresponding list.
Each issue includes a name and description. In Code View, the line number is shown, while in Form View the corresponding path is displayed. Clicking on the issue navigates to the referenced section or line. Clicking the document icon of each issue (if available) redirects the user to the related Spectral documentation (standard validation rules only).
Post-conditions
The purpose is to quickly understand the type and the exact location of the issue detected.
OpenAPI 3.0 conversion
Preconditions
Having uploaded a specification different from version 3.0. In this case, it is easily recognizable from the interface, where all actions are disabled, with the only exceptions being the Code View tab and the Options button available to perform the conversion.
Steps
Press the Options button.
Select the only available option: “Convert to OpenAPI 3.0.”
Post-conditions
A notification will be displayed indicating the outcome of the operation. If the conversion is successful, all action buttons and tabs will be enabled, allowing the user to resume work.
Switching yaml and json format
Steps
Using the switch located at the top right of the Designer panel, it is possible to change the format from JSON to YAML and vice versa.
Post-conditions
The format change will be reflected not only in the Code View, but also in the fields used to define the schemas within the Form View.
Using the Designer Agent
The Designer Agent is available only if enabled for your installation.
The Designer Agent is the AI assistant of the API Designer. Open it with the Ask AI button in the top bar: it helps you create a new specification, enrich an existing one and fix the issues found by the validation. The proposed changes are shown in the Code View and are applied only if you accept them. See Designer Agent, in the AI Assistants section, for how to use it.
Download an OpenAPI specification file
Steps
Click the “Download” button located in the bottom button bar.
Post-conditions
A notification will be displayed indicating the outcome of the operation. If the operation is successful, the file will be downloaded locally in the format currently being displayed.