OpenAPI – Schema design

Quick start guide for OpenAPI schema design in Perseid Modeler.

The following text describes how to design a new Open API structure.

  1. Creating a new project
  2. Adding new elements to the Open API schema design
  3. Making modifications
  4. Defining specifications
  5. JSON schemas in OpenAPI
  6. Generating scripts
  7. Importing existing structures
  8. Generating HTML reports & Export to PDF

1. Creating a new project

To create a new project in Perseid Modeler click the New item on the main toolbar. A new modal form opens. Select OpenAPI project type, specify name, select version and click Create a new project. A new project is created and you can continue creating your Open API schema design.

New project for Open Api schema design.

2. Adding new elements to the Open API schema design

In Perseid Modeler you can add new objects via the dropdown menu. After creating a new project, the main graphical element representing the Open API schema will be displayed. Right-click on the element and select the item that corresponds to the desired node type.

New element added to Open API schema design.

Newly added node and newly defined dropdown submenu:

You can create an entire Open API structure in a similar way.

3. Making modifications

You can change the item name directly in the diagram.

Changing name

To change name or other properties, you can also either open the modal form by clicking the Edit button on the main toolbar or make changes in the right sidebar. For example define a description or define specifications in more detail.

Open API specifications in right side panel.

4. Defining specifications

Define specifications using code or the Specification assistant. The same specification can be defined in two areas. Either directly in the field Specifications:

Specifications written in code.

Or visually below the Specifications field, via user interface – input fields, dropdowns etc. The section below is called Specification assistant and it displays options relevant for selected node (title, termsOfService, version for the Info element etc.)

Specification assistant - UI.

The assistant displays the predefined properties and allows you to fill in only the values.
After entering a value, the code in the Specifications field is automatically updated.

5. JSON Schema in Open API

In the OpenAPI diagram in the schemas node there are definitions of classic JSON schemas. Therefore, the menu for exporting additional elements is the same as for JSON schemas. Perseid Modeler recognizes these specific items and offers the appropriate sub-menu.

To select a defined schema, then just enter the schema path in the Ref field.

6. Generating scripts for Open API

To generate a script for Open API, click the Script icon on the main toolbar. This will open a modal window where you will see a preview of the script.

Generated Open API script.

To save scripts to files, click Save script, define a location where the output should be stored and finish the action.

On the Generation settings tab, you have the option to choose whether the output will be JSON or YAML, and in the case of JSON format, whether it will be generated as Strict or not.

Json or Yaml

You can also preview the script in the right sidebar. Here, only the part of the script that corresponds to the selected element in the diagram will be displayed.

Partial script - YAML

7. Importing existing Open API structures

On the Projects page, click the Import button. Select a file and Perseid Modeler will load the structure and create a project with a diagram representing your Open API structure.

Import from files

Note: Import works with JSON schema files, we plan to import and create schema from JSON data in future releases.

8. Generating HTML reports

To export to PDF or to generate an interactive HTML report, click the Report button on the main toolbar. To generate a report, select the style and click Generate report. Follow the instructions to easily create documentation for your Open API schema design.

Open API - documentation and HTML report

#

Quick links

Free Trial Buy Now!

Blog categories