Add extra fields to a definition

[lafrech]

Sometimes, I need to add a field to a definition.

Typical use case: the discriminator field (search for "discriminator" in there, this comment also explains a lot and points some limitations). This can also be a vendor field (x-my_field).

I created a specific definition helper for that, but I think it could be in apispec itself. There is nothing specific in it. So here's the PR.

I first added this to marshmallow plugin schema_definition_helper, but then I realized it was not specific to marshmallow schemas, so I moved it to APISpec.definition. I'm leaving the two commits on purpose to expose the two approaches. I can squash into one or remove the last one depending on which approach is preferred.

This feature is pretty permissive. A more conservative approach would be to allow only fields that conform to the spec: a finite hardcoded list à la _VALID_PROPERTIES + the possibility to pass any vendor field (x-). I'm not sure this is needed. After all, the user adds extra_fields explicitly, so he should know what he is doing. It's not like we're harvesting in some Schema's metadata. BTW, I don't think discriminator should be defined in a field's metadata. It is schema level stuff. It shouldn't be in _VALID_PROPERTIES, right?

I'd be happy to hear your feedback about this.

[sloria]

Thanks @lafrech for the contribution . I think this serves a very common use case, so lgtm. 👍

[sloria]

This feature is pretty permissive. A more conservative approach would be to allow only fields that conform to the spec: a finite hardcoded list à la _VALID_PROPERTIES + the possibility to pass any vendor field (x-). I'm not sure this is needed.

I agree. For maintainability, I think it's best that apispec not try too hard to validate inputs. Perhaps we should add some docco that mentions this...

[sloria]

BTW, I don't think discriminator should be defined in a field's metadata. It is schema level stuff. It shouldn't be in _VALID_PROPERTIES, right?

Good catch. Fixed.