[RFC] Deprecate Blueprint.doc decorator

The Blueprint.doc decorator is meant to add documentation that can’t be inferred from the code or added by dedicated decorators. It allows the user to pass manual documentation that will be deep-merged with the automatically generated documentation. Unfortunately, it is not the silver bullet one would expect. It suffers from a few intrinsic issues.

We could try to play smart and improve the way the structure received by doc is used, but I’d rather add dedicated decorators or other explicit means to allow the user to pass documentation in a structured fashion, with a clear and thin abstraction layer.

I’d like to use this issue to list known issues about Blueprint.doc and use cases that should be covered by other means. The goal being to make it useless, and to deprecate it if possible.

Known issues

• It can’t really document arguments as deep-merging lists doesn’t work so it conflicts with auto-generated documentation.
• When adding extra documentation for a response, the user must use the same type for the status code than the one used in the response decorator (https://github.com/marshmallow-code/flask-smorest/issues/60#issuecomment-487856593).
• It doesn’t handle the OASv2 / v3 transparently, while the other decorators are pretty good at it, allowing the user to change the OAS version with a configuration parameter using the same codebase. For instance, it doesn’t add ['content']['application/json'] when using v3 which makes it more verbose to the user.

Use cases

• Add summary/description: Those can be passed in the view function docstring.
• Add examples: Can now be achieved with response/arguments decorators.
• Document specific API features (e.g. security information). Since this is quite specific, I think it could be done by a custom decorator defined in user code. Typically, when using a decorator to manage accesses to resources (generally from a flask third-party library), this decorator should be wrapped in a custom decorator that adds the information to the docs (see https://github.com/marshmallow-code/flask-smorest/issues/36#issuecomment-460826257 for an example). This means the _apidoc attribute mechanism becomes public API.
• Document / add extra-information to parameters. The only real need was for path parameters. Documentation for path parameters can be passed in Blueprint.route. (See #23)
• Document / add extra-information to responses. We could add a specific decorator for that. If we assume a view function can only have one normal response and other responses are errors (or error-likes such as redirections or “not modified”), then that decorator could be called “error”. (See #44)

[aiham]

Auto generating operationId probably goes against the original purpose of the field which was meant for customising the method name that openapi-generator is already auto generating. But I wouldn’t be against adding an auto generated operationId if the user explicitly requested one, I’m sure it would be useful outside the scope of openapi-generator.

I think keeping Blueprint.doc is probably the way to go, because injecting custom fields is actually a feature of OpenAPI: Specification Extensions. Extensions are especially useful for new spec-consuming tools that don’t exist yet or if someone wants to add some app-specific metadata to an operation. An example is the official swagger-node library which relies on the x-swagger-router-controller field.

We are also using Blueprint.doc for the operation-specific security rules (unless you can suggest a better way to do this?):

@blp.doc(security=[{"mySecurityScheme":[]}])

I think these are examples that you can’t necessarily guarantee the whole spec has been implemented by this library, but there’s also the case of new fields being added to the spec in the future that you can’t predict. It would be better to let library users extend it rather than restrict them. If that is via a differently named decorator I’d be happy with that too.

Also one comment on the known issue:

It can’t really document arguments as deep-merging lists doesn’t work so it conflicts with auto-generated documentation.

Maybe whatever is specified with Blueprint.doc (or a different decorator) should take precedence over anything auto generated. This allows library users to purposefully override something that they disagree with. For example, the official swagger-core Java annotations library explicitly allows you to override auto generated documentation: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#apiparam

While swagger-core scans these annotations by default, the @ApiParam can be used to add more details on the parameters or change the values as they are read from the code.

These are just my thoughts, hopefully you get some value from them. Thanks for flask-rest-api.

[lafrech]

Perhaps this SO post or this one would help. Keeping this for later.