Add OAS 3 URL with file extension

[Kate-Lyndegaard]

Feature Description:

The OAS 3 root document is available at openapi.json or openapi.yaml, with file extension.

Currently, deegree ogcapi makes it available at XX/api.

Definition of done:

OAS 3 document is available at openapi.json or openapi.yaml as specified in the Dutch API requirements and the Dutch validator.

The functionality is optional.

[stephanr]

Thank you for opening that feature request.

We see that this feature request has two separated topics. One part is the renaming of /api to /openapi. And the other is the handling of the encoding [1]. For this separate topic which we would prefer to be handled in a uniform way for all resources (e.g. collections).

It is also important to make sure that the overriding of the HTTP Accept header is handled consistently.

In general it would be nice to have a fixed order to describe the priority of encoding. For example:
1. Parameter (ex. f=json, accept=html)
2. Suffix (/collections.json, /collections.html)
3. Accept-Header
If you consider to change the list of priorities, please give use a short feedback.

[1] https://docs.ogc.org/is/17-069r3/17-069r3.html#encodings

[stempler]

I split the described functionality into three PRs:

• adding an alias "openapi" for the api endpoint
• support overriding the format/endcoding via query parameter or extension for all resources as suggested
• serve OpenAPI description as YAML in addition to JSON

[stempler]

Part of the related requirement in the Dutch API design rules is also that for the API definitions themselves "the CORS policy for this URI must allow external domains to read the documentation from a browser environment". Would anything speak against it from your side to for the YAML and JSON representations include an Access-Control-Allow-Origin: * response header?

This could be made configurable if it should be enabled, if that's desired. For that it would be helpful if you can comment on the question on your preferences related to introducing global configuration options for deegree OAF. Thanks!

[stempler]

An example service with two datasets that includes these changes (and a few others related to the issues we raised) is available here for testing.

[stempler]

I did a small update to the PRs:

• related to overriding the format I added support for the f query parameter in addition to the previously supported accept parameter
• to the PR with the OpenAPI description as YAML I also added the configuration option related to enabling CORS access from all origins for the API definitions only

From my side I don't have any pending changes left. Please let me know if you have any feedback on the PRs:

• Add "openapi" alias for api endpoint #80
• Add support for overriding accepted format #81
• Add OpenAPI description also in YAML format #82