Multiple Routes Swagger Documentation

[SteadBytes]

Motivation

See #288 for initial issue.

Using the doc parameter of Api.route() decorator applies documentation to the Resource as a whole. This prevents documentation being added on a per-route basis (for example adding an additional description to a route, or marking one route as deprecated) as the doc is applied to all routes.

Furthermore, each route uses the same Swagger operationId, causing both routes to be expanded at the same time when selecting one in the Swagger UI (the elements are selected using an HTML id which is set to the operationId.

Changes

• Using the doc parameter Api.route() will apply the documentation to that route only
• Routes using the doc parameter are given unique operationIds (combining the original operationId with the URLs provided)
• Each route will inherit documentation from the Resource (i.e. if applied using @api.doc, unless explicitly overridden with the doc parameter

Examples

Providing a description to a single route:

@api.route("/my-resource/<id>")
@api.route(
    "/also-my-resource/<id>",
    doc={"description": "Alias for /my-resource/<id>"},
)

class MyResource(Resource):
    def get(self, id):
        return {}

Expanding the first route only (note the description):

Expanding the second route only (note lack of description):

Inheriting/overriding from the Resource

@api.route('/my-resource/<id>', '/test/<id>')
@api.route('/also-my-resource/<id>', doc={"description": "Alias for /my-resource/<id>"})
@api.doc(params={'id': 'An ID'}, description="My resource")
class MyResource(Resource):
    def get(self, id):
        return {}

Expanding the first route only (note id parameter from @api.doc() but overridden description)

Expanding the second route only (note id parameter and description inherited from @api.doc() decorator):

Various combinations of the above can be used with of the available documentation parameters (description, id, params, deprecated etc).

[coveralls]

Coverage decreased (-0.3%) to 96.571% when pulling f9c1663 on 288-swagger-multiple-routes into e911078 on master.

[coveralls]

Coverage decreased (-0.3%) to 96.571% when pulling f9c1663 on 288-swagger-multiple-routes into e911078 on master.

[coveralls]

Coverage decreased (-0.3%) to 96.571% when pulling f9c1663 on 288-swagger-multiple-routes into e911078 on master.

[coveralls]

Coverage increased (+0.09%) to 96.914% when pulling 7f64f0b on 288-swagger-multiple-routes into e911078 on master.

[copdips]

even it's late, but a big thank to you.