New Feature: Validate with all properties required.

[flixx]

Hello.

We use openapi-core to validate our specs with the backend, so that we are sure that the documentation generated out of the specs is up-to-date.

However, so far, the validation only worked one-way: Properties returned in the response of the backend that are missing in the specs generate an error. (good) Properties in the specs that are not returned in the response of the backend generate no error unless they are required (bad).

One solution would be, of curse, to set all properties to required. However, we do not want to do that since it is 1. confusing in the documentation 2. a lot of work.

This PR introduces require_all_props It can be set like this:

RequestValidator(spec, require_all_props=True)
# or
ResponseValidator(spec, require_all_props=True)

If it is set to true, it is simulated that all properties defined in the specs are required.

Felix

[codecov[bot]]

Codecov Report

Merging #146 into master will increase coverage by 0.25%. The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #146      +/-   ##
==========================================
+ Coverage   96.19%   96.44%   +0.25%     
==========================================
  Files          58       58              
  Lines        1602     1605       +3     
==========================================
+ Hits         1541     1548       +7     
+ Misses         61       57       -4

Impacted Files	Coverage Δ
openapi_core/schema/media_types/models.py	85.29% <100%> (ø)	:arrow_up:
openapi_core/schema/schemas/models.py	96.67% <100%> (+0.01%)	:arrow_up:
openapi_core/schema/parameters/models.py	96.82% <100%> (ø)	:arrow_up:
openapi_core/validation/response/validators.py	100% <100%> (ø)	:arrow_up:
openapi_core/schema/schemas/unmarshallers.py	100% <100%> (ø)	:arrow_up:
openapi_core/validation/request/validators.py	100% <100%> (ø)	:arrow_up:
openapi_core/compat.py	100% <0%> (+44.44%)	:arrow_up:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 0e30b71...0b34ed1. Read the comment docs.

[codecov[bot]]

Codecov Report

Merging #146 into master will increase coverage by 0.25%. The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #146      +/-   ##
==========================================
+ Coverage   96.19%   96.44%   +0.25%     
==========================================
  Files          58       58              
  Lines        1602     1605       +3     
==========================================
+ Hits         1541     1548       +7     
+ Misses         61       57       -4

Impacted Files	Coverage Δ
openapi_core/schema/media_types/models.py	85.29% <100%> (ø)	:arrow_up:
openapi_core/schema/schemas/models.py	96.67% <100%> (+0.01%)	:arrow_up:
openapi_core/schema/parameters/models.py	96.82% <100%> (ø)	:arrow_up:
openapi_core/validation/response/validators.py	100% <100%> (ø)	:arrow_up:
openapi_core/schema/schemas/unmarshallers.py	100% <100%> (ø)	:arrow_up:
openapi_core/validation/request/validators.py	100% <100%> (ø)	:arrow_up:
openapi_core/compat.py	100% <0%> (+44.44%)	:arrow_up:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 0e30b71...0b34ed1. Read the comment docs.

[bjmc]

Properties in the specs that are not returned in the response of the backend generate no error unless they are required (bad).

Could you explain this a little more? If those properties aren't required in the spec, then they are optional. Why is it bad to not return an error for optional properties being omitted? If all the properties are required, they should all be marked required in the spec.

Maybe there's something subtle I'm misunderstanding here.

[flixx]

Sure @bjmc @p1c2u: We publish an API Documentation based on our OpenAPI Spec to our customers. We want to ensure that the Documentation is always up-to-date.

In order to ensure that all fields that are in the Specs are in the response of our Backend, we would need to set every single property as required.

I think the term "required" does not really make sense when you talk about responses. In our API Documentation, we want to tell the API-User what properties are "Required" in the Request, yes, but naming something "required" in the Response, does not really make sense - our Backend always gives a Response with a complete list of all properties (some of them are nullable).

So, yes technically, it would be most right to always mark all fields in the Response Schemes as required. But practically, this is both a lot of work (it is easy to forget to add new properties to the required list) and strange for a reader of a documentation.

So I understand your point - but the changes I suggest here already helped us to make our API Documentation a lot better.

Felix

[spacether]

@flixx if this is always the case then why not add an automated postprocessing step that marks all response schema properties as required and generates the updated spec. That way it will always be done.