Generate OpenAPI specification

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

  • Click the Generate on menu.
    A menu offers one option to generate the OpenAPI specification. +:

    • OpenAPI specification — continue with this one

      Generate document

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

  • Select JSON or YAML as the desired file format.

  • Set the Base URL were the Aspect API will be served from.

  • Select the preferred option for paging:

    • Cursor-based paging

    • Offset-based paging

    • Time-based paging

  • Check 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.

  • Check 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.

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

  • Click Generate and store the Open API 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.

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.

Generate 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.