Add documentation into API definition for release v0.2.0 (issue #18)

[jpengar]

What type of PR is this?

• documentation

What this PR does / why we need it:

Update API documentation according to v0.2.0 API version definition including changes from v0.1.0 release. The documentation will be added to the API definition as discussed in camaraproject/WorkingGroups#164. It was agreed that the CAMARA documentation should be embedded in the OAS definition and not separate. This will reduce the effort to maintain the documentation.

This PR is aligned to QualityOnDemand PR camaraproject/QualityOnDemand#151

Which issue(s) this PR fixes:

Fixes #18

Special notes for reviewers:

• Multi-line descriptions formatted as |
• External resources such as images and other docs are linked to the absolute paths in Github: ![Alt text](https://raw.githubusercontent.com/full_path)
• Most part of the documentation is part of info.description:
  • I have renamed some sections: "Quick Start" to "Relevant terms and definitions", "API documentation, Details" to "API functionality"
  • Added section "Further info and support" as in legacy doc, with "(FAQs will be added in a later version of the documentation)". To be discussed if we maintain this as part of the spec or separately, or separately but linked in the spec.
• " Authentication and Authorization" section is removed and content moved to the standard securitySchemes descriptions

Visualizations tested with editor.swagger.io and app.redocly.com

Changelog input

 CAMARA documentation is now embedded within the OAS definition, and not separate. 

[jpengar]

@rartych @bigludo7 Kindly reminder. If you could take a look at this, please.

[rartych]

I have rendered the documentation using ReDoc.

Currently API Support mail and URL and Terms of Service leads to example.com
I guess in the final version it should direct to CAMARA own resources - I am not sure if they are available yet.

Similarly

externalDocs:
  description: Project documentation at CAMARA
  url: https://github.com/camaraproject/

Should rather point to https://camaraproject.org/home-devices-qod/

[jpengar]

Currently API Support mail and URL and Terms of Service leads to example.com
I guess in the final version it should direct to CAMARA own resources - I am not sure if they are available yet.

Yes or maybe leave it as is. Is the same situation in other API projects... e.g. https://github.com/camaraproject/QualityOnDemand/pull/151/files

Whatever we may agree in the future.

Similarly

externalDocs:
description: Project documentation at CAMARA
url: https://github.com/camaraproject/
Should rather point to https://camaraproject.org/home-devices-qod/

This is the same situation. But this is also aligned with other subprojects like QualityOnDemand. Actually, I think it is fine to point to the CAMARA project as a reference to external documentation. Because it can refer not only to Home Devices QoD documentation, but actually to Commonalities or any other general documentation in CAMARA.