Codecov Report

Merging#146 intomaster willincrease coverage by0.25%.
The diff coverage is100%.

@@            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

Continue to review full report at Codecov.

Legend -Click here to learn more
Δ = absolute <relative> (impact),ø = not affected,? = missing data
Powered byCodecov. Last update0e30b71...0b34ed1. Read thecomment docs.

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.

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 theRequest, yes, but naming something "required" in theResponse, 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

@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.