FUL-11652: Allow entity endpoint versioning documentation

[MartinDamov]

BLOCKED:

The current provider we use for hosting the API docs (https://stoplight.io/) doesn't seem to support openapi 3. We have inquired about the support but until they don't support this PR will be blocked.

Setting up

When changing the wsgiservice_restplus, one should use local version instead of the installed one. The following code can be included in the Dockerfile.dev file to copy over the local content (assuming it is in the beekeeper folder for simplicity) and install it with using pip from the local folder.

...
COPY ./wsgiservice-restplus /opt/beekeeper/wsgiservice-restplus
RUN pip install -e /opt/beekeeper/wsgiservice-restplus

TODO:

• Update the swagger 2 to openapi 3
• The structure of the generated swagger.json should be updated to meet the requirements for the openapi 3
• Allow path responses to include multiple content types. Each content different content type should hold reference to a model.

The structure of the responses with openapi 3 should be the following:

                get:
                  summary: FooBar
                  responses:
                    '200':
                      description: FooBar
                      content:
                        application/json:  # Specify content type
                          schema:
                            $ref: '#/definitions/StreamMember'  # Model specific for the content type
                        application/vnd.io.beekeeper.stream_membersv2+json:
                          schema:
                            $ref: '#/components/StreamMemberv2'