[Task] Evaluate improvements to OpenAPI spec generation

[chris-volk]

Creating APIs from OpenAPI specs generated by Aspect Models is a typical way from model to API. Users have given the feedback that they'd be interested in additional features to create (&document) their API in the best possible way.
Their ideas include:

• specify which endpoints are specified -> BUT, we are agnostic, not only REST. To be evaluated
• improve(?) input to add code snippets as defined in openAPI spec -> this already exists, see https://eclipse-esmf.github.io/esmf-developer-guide/2.2.2/tooling-guide/samm-cli.html#using-the-cli-to-create-a-json-openapi-specification To be discussed with https://github.com/Kostadin-Ivanov who proposed the idea; maybe adjust documentation with an example from a use case? Potentially add a way to locally store your snippet in a file etc?

With the option --resource-path "/resources/{resourceId}" the generator constructs the URL https://www.example.org/api/v1/{tenantId}/resources/{resourceId} and then the --parameter-file defines the parameter resourceId in yaml:

As the result of this issue an ADR shall be created that defines the target definition of OpenAPI spec generation.

See also related
#451
#340
#195
#453