feat: add required to responseField tag and append the required fields to generateResponseContentSpec for object types

[yannick-softwerft]

Extends the documentation for @responseField tags by adding the required field.

Format before was:

// Format:
// @responseField <name> <type>  <description>

Format after is:

// Format:
// @responseField <name> <type> <"required" (optional)> <description>

If required is set in the documentation it will set the new $required- property (ResponseField Dto) to true.
All fields that have the required property set to true will be added to the openapi spec for object types.

[shalvah]

Could you add some tests as well? You don't necessarily need to add new tests, just find some of the tests around @responseField and #[ResponseField] and ensure they generate the correct parameter values. Also add some cases in the OpenAPI spec writer test that handle required/optional.

[yannick-softwerft]

Could you add some tests as well? You don't necessarily need to add new tests, just find some of the tests around @responseField and #[ResponseField] and ensure they generate the correct parameter values. Also add some cases in the OpenAPI spec writer test that handle required/optional.

Yes, I will do that, but I will probably not be able to do it until 15.03.2024.

[shalvah]

Ready for review? It's still marked as draft.

[sotdan]

Hey @shalvah, I am a colleague of @yannick-softwerft and I finally found some time to continue work on this PR.

I started writing tests and then I realized that this feature also has to support response fields where the entire path is specified. It is now implemented and ready for review.

[yannick-softwerft]

LGTM

[shalvah]

Can you add support in the #[ResponseField] attribute as well? Should be easier, since there's no parsing needed.

[sotdan]

That was actually working already.

BTW: I think it's kind of a breaking change. required has the default value true in Knuckles\Scribe\Attributes\ResponseField, so if you don't specify required as false in your attribute, the ResponseField is treated as required and is suddenly marked as required in the openapi spec.

I demonstrate this in the changes I just made in tests/Strategies/ResponseFields/GetFromResponseFieldAttributesTest.php.

Maybe the default value of required in the ResponseField attribute has to be changed to false?

[shalvah]

Hmm, I think it is technically breaking, but likely low impact, so I wouldn't want to hold it back.

[shalvah]

Thanks!