Example in README doesn't work with apispec >= 2.0.0

[smsearcy]

The docstring example for the response schema in README.md does not work with the current master branch because apispec changed how to reference schemas in apispec 2.0. When using the example format of $ref: "#/definitions/BarBodySchema" I get the following error:

Could not resolve reference because of: Could not resolve pointer: /definitions/BarBodySchema does not exist in document".

Per the upgrade docs (and my testing) I think the docstring should look like this:

@view_config(route_name='foo_route', renderer='json')
def foo_view():
    """A greeting endpoint.

    ---
    x-extension: value
    get:
        description: some description
        responses:
            200:
                description: response for 200 code
                content:
                    application/json:
                        schema: BarBodySchema
    """
    return 'hi'

[smsearcy]

Playing some more with the demo site I realized that part of my issue was using OpenAPI version 3.0.2 instead of 2.0. So I'm going to submit a PR to bring the README in sync with the demo app rather than what I had above.

[ergo]

I think this is now corrected too?

[smsearcy]

Good question, I need to double check, it's been a while since I looked at this closely. Now I'm second guessing whether the $ref: issues were due to changes in the apispec library or the OpenAPI version used. What if I update the example to mimic the apispec example application, using version 3.0.2 of OpenAPI?

[ergo]

Yeah, I think we should generally try to support latest apispec and OpenAPI but my experience in the past tells me its really a moving target :)