Quick start guide for OpenAPI schema design in Perseid Modeler.
The following text describes how to design a new Open API structure.
- Creating a new project
- Adding new elements to the Open API schema design
- Making modifications
- Defining specifications
- JSON schemas in OpenAPI
- Generating scripts
- Importing existing structures
- 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.
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.
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.
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.
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:
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.)
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.
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.
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.
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.
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.
#