OpenApiSpec (OAS) Links

[sebbader]

What?

Add OpenApiSpec (OAS) Links to the Spec to specify the relationship of routes within OAS, e.g. which responses of which routes can be used for a request to another route. These definitions allow automated stateful testing with certain testing libraries.

How?

Add links to the spec.

This issue relates to finding ACPLT-5.

[sebbader]

Explanation of OAS Links: https://swagger.io/docs/specification/links/

[sebbader]

I have added a few examples, e.g.,

aas-specs-api/Entire-API-Collection/openapi.yaml

Line 1134 in 133e28e

links:

Lessons learned:

• OAS Links are there and work.
• They increase the clarity as the relations between the API Operations indeed can be modelled now.
• They have limitations how to select array entries as there are no wildcards allowed. This means that a complete expression of what we have in mind with "Use return value from here as an input parameter there" is not sufficiently possible.
• Necessary base64 encoding operations can not be modelled, only described in human-readable text.
• It adds a lot of new lines, massively decreasing the readability of the YAML. And, that's actually way more important, also the maintainability of the YAML files.

My personal conclusion is therefore to observe this feature further but to not add it yet, mainly due to the last point.

[noheton]

+1 @sebbader
HATEOAS is a great concept. But is very difficult to scale and maintain.
Sidenote: in another project we dropped HATEOAS support for some of these reasons.

[sebbader]

Closing the issue due to the thereby introduced immense overhead in the OpenApi files.