Why does apispec validation fail on format similar to documentation example for Python Flask API backend?

Question

I am using apispec in a Python/Flask API backend. i followed the format found in the apispec documentation example. See: https://apispec.readthedocs.io/en/latest/ Can anyone tell me why I am getting a validation error with the below json schema and data? It says "responses" is required but it looks like it is there. Is the structure incorrect? Any help appreciated!

openapi_spec_validator.exceptions.OpenAPIValidationError: 'responses' is a required propertyFailed validating 'required' in schema['properties']['paths']['patternProperties']['^/']['properties']['get']:
    {'additionalProperties': False,
     'description': 'Describes a single API operation on a path.',
     'patternProperties': {'^x-': {'$ref': '#/definitions/specificationExtension'}},
     'properties': {'callbacks': {'$ref': '#/definitions/callbacksOrReferences'},
                    'deprecated': {'type': 'boolean'},
                    'description': {'type': 'string'},
                    'externalDocs': {'$ref': '#/definitions/externalDocs'},
                    'operationId': {'type': 'string'},
                    'parameters': {'items': {'$ref': '#/definitions/parameterOrReference'},
                                   'type': 'array',
                                   'uniqueItems': True},
                    'requestBody': {'$ref': '#/definitions/requestBodyOrReference'},
                    'responses': {'$ref': '#/definitions/responses'},
                    'security': {'items': {'$ref': '#/definitions/securityRequirement'},
                                 'type': 'array',
                                 'uniqueItems': True},
                    'servers': {'items': {'$ref': '#/definitions/server'},
                                'type': 'array',
                                'uniqueItems': True},
                    'summary': {'type': 'string'},
                    'tags': {'items': {'type': 'string'},
                             'type': 'array',
                             'uniqueItems': True}},
     'required': ['responses'],
     'type': 'object'}
On instance['paths']['/v1/activity']['get']:
    {'get': {'description': 'Activity Get',
             'responses': {'200': {'content': {'application/json': {'schema': 'ActivitySchema'}},
                                   'description': 'success'}},
             'security': [{'AccessTokenAuth': []}],
             'tags': ['user', 'admin']}}

For reference, here is the original source comment that the data comes from:
        """
        ---
        get:
          description: Activity Get
          responses:
            200:
              description: success
              content:
                application/json:
                  schema: ActivitySchema
          security:
            - AccessTokenAuth: []
          tags:
            - user
            - admin
        """

score 0 · Answer 1 · answered Apr 12 '21 at 21:23

I found the answer in the apispec documentation at: https://apispec.readthedocs.io/en/latest/using_plugins.html#example-flask-and-marshmallow-plugins where it says: "If your API uses method-based dispatching, the process is similar. Note that the method no longer needs to be included in the docstring." This is slightly misleading since it's not "no longer needs to be included" but rather "cannot be included". So the correct doc string is:

        """
        ---
        description: Activity Get
        responses:
          200:
            description: success
            content:
              application/json:
                schema: ActivitySchema
        security:
          - AccessTokenAuth: []
        tags:
          - user
          - admin
        """

Why does apispec validation fail on format similar to documentation example for Python Flask API backend?

1 Answers1