Support documentation of validator functions in Swagger about flask_accepts

[apryor6]

Actually, it does not appear that RESTplus documents validators in Swagger. If that is the case, the existing functionality should be sufficient as you are getting the improved error messaging/validation from Marshmallow while also maintaining the equivalent level of documentation.

@flayman if you disagree feel free to reopen for discussion.

[flayman]

Hi. Sorry, it's been a long weekend here. There are validators on the one hand, and constraints on the other. Marshmallow deals seems to deal with all constraints through validators. Flask-restplus and Swagger use json schema, which has constraints you see as dictionary properties. For example:

...
    "definitions": {
        "MySchema": {
            "type": "object",
            "properties": {
                "createdBy": {
                    "type": "integer",
                    "format": "int32"
                },
                "name": {
                    "type": "string",
                    "maxLength": 25
                },
                "description": {
                    "type": "string",
                    "x-nullable": true
                }
            },
            "required": [
                "name"
            ]
        },
...

The maxLength property there will cause Swagger to reject input longer than 25 characters with a response like:

{
  "errors": {
    "name": "'asdfasdfasdfasdfasdfasdfasdgsdgasdfherfjhsdf hdfhsdfhsd fh sdfh sdfh sdfhsd fhs dfhsd f hsdfh sdfh sdfh sdfh' is too long"
  },
  "message": "Input payload validation failed"
}

This is not such an issue, as you say, because Marshmallow will reject it and you just pass the error back in the response. However, this is more consistent and it's a safety valve. It seems to me that you need to try to build the swagger.json to be correct since it is the description of the API. There are other advantages, such as that some clients may be able to do client side validation. The constraints are not part of the documentation, but the example values that are generated will make use of default values. That's very handy.

[apryor6]

Ah okay, I see. On the one hand, Marshmallow provides better error messages, including the length parameter instead of just "too long":

{'name': ['Longer than maximum length 25.']}

The error is going to be raised from wherever the point of failure is, so if we were to manually map any Marshmallow validation to json schema internally, the Marshmallow errors would still be what came back from the API itself, making the mapping pointless if that is all it affects.

To that end, are there other uses or tools that consume the swagger.json file? Considering I didn't see anything in the generated swagger docs regarding validation, I didn't see much value in creating an internal mapping of validators and the user can provide either kind. However, if there is tooling that takes the swagger.json as input then it would seem more valuable to create a bridge for mapping marshmallow validation to RESTplus.

[flayman]

I don't really know. It would be useful to invite comment from the flask-restplus maintainers. To be clear, I'm not one. This is probably really more of a pure Swagger thing. The maintainers will be better able to comment on completeness. I feel confident in saying that support for a lot more of the types will be needed though.

[flayman]

By the way, good work on all of this. It's looking good. The code is well structured and you're very quick to put out releases.

[apryor6]

As far as types go, that list was recently expanded (see here)

There's still a number that map to Raw that might not need to, and a few that have been missed by the first pass. Agreed it would be good to flesh that out more.

[j5awry]

To that end, are there other uses or tools that consume the swagger.json file?

Inside flask-restplus, not that I'm aware of. Outside flask-restplus, yes. There's a large number of tools for autogenerating clients that focus on using the swagger.json. Here is one such examples we've used at work:

https://swagger.io/tools/swagger-codegen/

[apryor6]

Got it. In that case my opinion on mapping validators across Marshmallow and RESTplus internally in flask_accepts is not a priority because:

1. All of the validation methods from both RESTplus and Marshmallow can already be used. This includes validation errors being bundled together in cases where both reqparse and marshmallow raised exceptions
2. RESTplus doesn't display the validation data anywhere in the docs, meaning there is no loss of documentation experience when using marshmallow through flask_accepts
3. This mapping would be a lot of work, with the only known benefit be for a user of flask_accepts that was also exporting the Swagger spec into some third party tool.

This is certainly revisitable should interest arise, but for now I won't pursue this.