feat: update error messages

[danut-t]

Currently, the error messages make the debugging hard, as it is difficult to figure out where are there issues (in the request or the documentation), for which request it is happening and what's the exact problem and the expectation.

This PR aims to fix that (partially) by changing a few things:

1. Change how the reference is created:
   The existing reference contained minimal information and it also had a bug where it would continuously attach fields to it, even when it should have pointed to only one field. The new format will contain informations about the request path and type, if it's the request or response, and the drilldowned path to the key with the issues (if it's the case)

The new format will look like this: '<request_type> <request_path> > <request/response> > <status_code(for responses)> > path > to > key'

and in practice it could look like this: GET /api/pets > response > 200 > name > id

2. Add whenever possible the actual request/response body and the schema section for easy comparison

Update most of the messages to include, besides the new reference, a copy of the actual body and the schema section, along with (hopefully) clearer language as to what went wrong. The combination of these and the new reference should provide enough information to quickly investigate the issue without have to take the request and the documentation and scan for differences side by side.

Examples of how it would look like:

missing property from the request data

E               openapi_tester.exceptions.DocumentationError: The following property was found in the schema definition, but is missing from the request data: "name"
E               
E               Reference:
E               
E               POST /api/pets > request > name
E               
E               Request body:
E                 {
E                   "tag": "dog"
E               }
E               Schema section:
E                 {
E                   "name": {
E                       "type": "string"
E                   },
E                   "tag": {
E                       "type": "string"
E                   }
E               }
E               
E               Hint: Remove the key from your OpenAPI docs, or include it in your API request

missing property from the response data

E               openapi_tester.exceptions.DocumentationError: The following property was found in the schema definition, but is missing from the response data: "width"
E               
E               Reference:
E               
E               GET /api/v1/cars/incorrect > response > 200 > width
E               
E               Response body:
E                 {
E                   "name": "Saab",
E                   "color": "Yellow",
E                   "height": "Medium height"
E               }
E               Schema section:
E                 {
E                   "name": {
E                       "type": "string",
E                       "maxLength": 254
E                   },
E                   "color": {
E                       "type": "string",
E                       "maxLength": 254
E                   },
E                   "height": {
E                       "type": "string",
E                       "maxLength": 254
E                   },
E                   "width": {
E                       "type": "string",
E                       "maxLength": 254
E                   },
E                   "length": {
E                       "type": "string",
E                       "maxLength": 254
E                   }
E               }
E               
E               Hint: Remove the key from your OpenAPI docs, or include it in your API response

Besides all of these, another minor change is to use by default json.dumps on data whenever the content is application/json in order to reduce verbosity in tests

Additionally Part 3: added support for OAS 3.1 lists of types e.g.:

    NewPet:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'

[maticardenas]

@danut-t thanks for this change, IMO this is a huge improvement to the main goal of this package, which is informing these inconsistencies. Just left a comment about the minor change of the json serialization on this package's side.

[danut-t]

@maticardenas Hmm I don't see the comment, could you link it to me please?

[maticardenas]

@danut-t it should be visible now, I had forgotten to “submit the review” and it was only visible to me

[kazantsevaanna]

So nice! These error messages are so useful 😻