Designing APIs
Introducing
The Designer section in ApiShare can be accessed from the main menu and provides functionality for creating and editing OpenAPI specifications. This section is designed to be easily used by users with different levels of experience and expertise for generating OpenAPI specifications.
Accessing to API Designer
Preconditions
Available to all user types except Visitor
Steps
Navigate to
Designerfrom the main menu.
Post-conditions
The user can view, Create, Modify, Validate, Test and save ad OpenAPI specification.
Upload of a 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 modal, click “Browse file” to select a file from your local machine among the supported formats (max 10 MB). Then click load.
Post-conditions
A push notification will be displayed indicating the outcome of the operation. If the upload is successful, all the data will be available in the forms 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 of a 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, 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 (an 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.
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.
Leveraging the AI Assistant
The AI Assistant (if enabled) can be activated via the dedicated “Ask AI” button in the top bar of the API Designer. It will appear as a side panel, substituting the Preview or the Linting panel.
The AI Assistant in the API Designer provides a guided AI experience wherein the user can chose between 3 different activities:
Generating the Specification
Preconditions
No edits have been made to the specification yet.
Steps
The user clicks the suggested prompt for creating a new OpenAPI Specification.
Using the prompter at the bottom, and if necessary applying any suggestions which appear when the prompter is in focus, the user describes the requirements and functions of their API.
The user can also attach documents and files to add additional context.
The user sends the request and, after elaboration, they are invited to review the AI’s output via the Code View.
The user may see the differences in the code view, edit them, then finally accept or reject them.
Post-conditions
The OpenAPI Specification is created. The user can explore it in the Code View or Form view interchangeably, as well as visualize its preview with the dedicated Preview panel.
Enhancing or Changing the Specification
Preconditions
A pre-existing specification has been loaded, or an edit has been made.
Steps
The user clicks the suggested prompt for enhancing the OpenAPI Specification.
Using the prompter at the bottom, and if necessary applying any suggestions which appear when the prompter is in focus, the user describes the modifications of their API.
The user can also attach documents and files to add additional context.
The user sends the request and, after elaboration, they are invited to review the AI’s output via the Code View.
The user may see the differences in the code view, edit them, then finally accept or reject them.
Post-conditions
The OpenAPI Specification is edited. The user can explore it in the Code View or Form view interchangeably, as well as visualize its preview with the dedicated Preview panel.
Fixing Linting Issues in the Specification
Preconditions
A pre-existing specification has been loaded, or an edit has been made, and the specification has some validation errors.
Steps
The user validates the Specification either via the “Validate” button, or via the suggested action by the AI assistant.
The user clicks the suggested prompt for fixing any errors and inconsistencies in the OpenAPI Specification.
The user waits for the elaboration to complete, after which they are invited to review the AI’s output via the Code View.
The user may see the differences in the code view, edit them, then finally accept or reject them.
Post-conditions
The OpenAPI Specification now has no errors. The user can explore it in the Code View or Form view interchangeably, as well as visualize its preview with the dedicated Preview panel.
Download of a 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.