Generate OpenAPI specification

To generate an OpenAPI specification from the Aspect Model, proceed as follows:

The generate OpenAPI dialog will open: Generate OpenAPI document

  • In case your model supports multiple languages, select the specific language for the documentation.

  • Select JSON or YAML in the Output file format drop-down.

  • Set the base URL where the Aspect API will be served from.

  • Select the preferred option for paging:

    • Cursor-based paging

    • Offset-based paging

    • Time-based paging

  • Select the Include Query API checkbox, if you need a path section for the Query API Endpoint of the Aspect API to be included in the specification.

  • Select the Use Semantic Version checkbox, if you need the complete semantic version of the Aspect Model to be used as the version of the API. Otherwise, only the major part of the Aspect Version is used as the version of the API.

  • Select the Active Resource Path checkbox, if you need the active resource path to be included in the specification.

  • Select the Include POST, Include PUT, Include PATCH checkboxes, if you need the corresponding backend functionality.

  • Click Generate and store the OpenAPI specification file locally.

Configuring Resource Path in the OpenAPI Generation Dialog

When the resource path is activated, additional fields are introduced in the OpenAPI Generation Dialog to allow for its configuration. The inclusion of certain properties in the output depends on the selected output file format:

  • YAML: a property file in YAML format is required when YAML is chosen as the output file format.

  • JSON: a property file in JSON format is needed if JSON is selected.

It is crucial to ensure that the properties in the file match those specified in the resource path. Failure to do so will result in an error prompting a review of the mismatches.

Generate OpenAPI document

If you run into errors, please make sure that the graph is valid.
If the invalid element is not highlighted with a red border, click the Validate icon to get a hint.

For additional details on configuring the Resource Path and generating OpenAPI specifications using the SAMM CLI, please consult our comprehensive guide: Generating OpenAPI Specifications with SAMM CLI.