[Request] Add customization of OpenAPI exports

[Kostadin-Ivanov]

Is your task related to a problem? Please describe.
Could we have a functionality which can be used to customize the exported OpenAPI?

Currently the generated OpenAPIs are pretty focused on a digital twin system (DTS) and are provided mainly with GET and POST (when 'IncludeQueryApi' is checked) operations.
I am not sure what is the other option: 'UseSemanticVersion' for, because I could not find any difference in exported OpenAPI model with or without it.

In general currently generated OpenAPIs - with and without 'IncludeQueryApi' have paths like: GET: /{tenant-id}/my-api-model and POST: /{tenant-id}/my-api-model, where each path has, currently it seems to be hardcoded URL parameter: tenant-id, and the POST operation has request body like:
{ "filter": "filter={filter expression}", "option": "option=limit({start},{count})" }
which, I guess is still quite DTS related and, here I am just guessing, provides for some sort of retrieving of specific elements of my-api-model, which I can specify in the filter.

Further, the currently generated OpenAPI provides the following responses: 200 - OK, 401 - ClientError, 402 - Unauthorized, 403 - Forbidden and 404 - NotFound with some predefined response bodies, which also seem to be DTS focused.

Describe the solution you'd like
Would it be possible to:

1. Allow option to either generate a DTS related (as per above) template OpenAPI or just simple (general) OpenAPI with all REST - CRUD: Create (PUT) Read (GET), Update (POST) and Delete operations
2. Allow option to select particular REST operations to be included, i.e. sometimes not all CRUD operations might be required for an OpenAPI model
3. Allow option to build paths for each element of the created AME - model, in the generated OpenAPI, i.e. to split paths for each element of the exported model
   For example: if my-api-model is for object like:
   { element1: "e1 value", element2: "e2 value", element3: {...} }
   The generated paths would be, lets take just a GET request:
   /my-api-model
   - to retrieve list with all available models
   /my-api-model/{id}
   - to retrieve particular object with specified id
   /my-api-model/{id}/element1
   - to get element1 from object with specified id
   /my-api-model/{id}/element3
   - to get the whole element3 for specified object id and so on and so forth.
4. Allow option to select / customize responses.
   For example: the only responses required might be 200 - OK and 404 - NotFound. Further in case of creation, maybe new response: 201 - Created could be added etc.
5. Also, in case of not a DTS focused OpenAPI, would it be possible to avoid the hardcoded {tenant-id} and add some custom parameters like: id, as per above example paths

Describe alternatives you've considered
With current implementation of OpenAPI exports, if I want to achieve above OpenAPI adjustments, I have to take generated OpenAPI for myApiModel and then manually do these updates.

With regards to implementation, I am not sure, but either: having option to specify a template which then can be "imported" or having some kind of parameters for above customization might be one way to be implemented in the SDK.
With regards to AME - UI, probably some check options / buttons or functionality to "import" templates might be one way to achieve this.

Additional context
Currently not available, but if required I can provide some.

[chris-volk]

We adjusted the OpenAPI generation with additional configuration, see #565.
The other items in this request (POST requests to change/update entities, Configure CRUD operations & Separate resources for every property) are out of scope for now since SAMM Entities have no ID that could be used to construct a corresponding resource

[Kostadin-Ivanov]

Thank you Chris.

Just to confirm about this customization is now available (visible in AME 5.5 and above), but as per our last chat,
did the original (default) behavior of the OpenAPi generation was kept, in case when user does not provide a template and path values?
- as per AME 5.5 - when path is not provided, the generated OpenAPI gets default name similar to: en-open-api.yaml and template was set as required input, but the docs were not providing example templates, which a user can follow.

Has this been addressed?

[atextor]

Hi @Kostadin-Ivanov,
let me summarize the current state:

• Points 1 and 2 of this issue's description have been adressed in Create PUT/PATCH/POST methods for OpenApi #573. When generating the OpenAPI spec, PUT/PATCH/POST endpoints can be separately enabled/disabled.
• Point 3 can not be directly solved in the scope of the esmf-sdk or the OpenAPI generation, because it builds on the notion of IDs for the data described by Entities (so that the ID can be made part of the resource path). This is an enhancement that would have to be made in the meta model first to allow modellers to specifify which Property (or set of Properties) uniquely identifies the datum. Please feel free to open a SAMM issue to further discuss this.
• Point 4 has been addressed in Added template for OpenaApi spec generation #565. With a the generation template you can control more details, such as error responses.
• Point 5 addresses variables in the resource path, these are not hard-coded but only defaults are provided. When using samm-cli, you can override them using the --resource-path option, see Using the CLI to create an OpenAPI specification for details.
• Regarding the AME questions, as far as I know this is solved in AME 5.6.0; the corresponding PR is Fix the name of the generated API file esmf-aspect-model-editor#232. If you encounter non-desired behaviour, please open an AME issue.

[Kostadin-Ivanov]

Hello @atextor ,
Thank you for this update.

I presume that these are yet to be released in next release for Aspect Model Editor.

Thank you for your support again.
If there is any problem with the AME, I will let you know and raise a ticket, as you suggested.