Add guidance for Info object in apis

[RandyLevensalor]

OpenAPI Info Object

Provide guidance on the info-object. For instance the following fields could have consistency.

  termsOfService: http://swagger.io/terms/
  contact:
    email: project-email@sample.com

[shilpa-padgaonkar]

https://github.com/camaraproject/WorkingGroups/discussions/260

[tanjadegroot]

As discussed in the https://wiki.camaraproject.org/display/CAM/2024-05-14+Release+WG+Minutes, it was checked, but the {variable} concept cannot be applied to the Info object.

The following content of Info Object below is proposed to be put in the Commonalities API Design guidelines:

The Info object shall have the following content, which needs to be adapted by the provider implementing the API.

info: title: without “API” in it, e.g. "Number Verification" description: | <text explaining the API, part of the API documentation> e.g. "This API allows to verify that the provided mobile phone number is the one used in the device. It verifies that the user is using a device with the same mobile phone number as it is declared. ..." - this should include a section on the authentication version: 1.0.1 - Aligned to SemVer 2.0 according to CAMARA design guidelines termsOfService: http://example.com/terms/ - to be replaced by the provider's terms contact:   name: - check if we can put variables here   url:   email: license:   name: Apache 2.0   url: https://www.apache.org/licenses/LICENSE-2.0.html

In addition, the following can be added to the Commonalities common.yaml file:

info: title: Number Verification description: | This API allows to verify that the provided mobile phone number is the one used in the device. It verifies that the user is using a device with the same mobile phone number as it is declared version: 0.2-alpha.1 termsOfService: http://example.com/terms/ contact: name: API Support url: http://www.example.com/support email: support@example.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html

@hdamker to please transfer this issue back to commonalities to to a PR with the above changes.