Add APIFAIRY_APISPEC_VERSION config option

[Danthewaann]

Added a new APIFAIRY_APISPEC_VERSION config option to allow users to specify what openapi documentation version they want to generate for their project via apispec. Currently you have to use the @webhook decorator just to be able to do this, which not all projects use. The default behaviour has been preserved to not cause any breaking changes, which is to use 3.1.0 if the @webhook decorator is used or fall back to 3.0.3 if APIFAIRY_APISPEC_VERSION is not provided.

I also updated the existing tests to work with latest versions of marshmallow and flask. I also added some new tests to cover the new APIFAIRY_APISPEC_VERSION config option.

[miguelgrinberg]

Hi, thanks for your contribution!

The problem that I see with this change is that it isn't doing anything other than stamping the version you provide. It is misleading, because one would think that if you request a given version of OpenAPI then the definitions will be made compatible with that version, or at least an error would be generated if this cannot be done, but none of that is done, so changing the default version selected by this package is very likely going to get you in trouble.

Also you have made it so that the version that you specify is completely ignored when webhooks are defined. This is also unexpected.

I really prefer to leave which version to use up to this package. If you need to do an override and you know what you are doing, then you can add a process_apispec handler and modify the generated spec as you need.

[Danthewaann]

Hi, thanks for your contribution!

The problem that I see with this change is that it isn't doing anything other than stamping the version you provide. It is misleading, because one would think that if you request a given version of OpenAPI then the definitions will be made compatible with that version, or at least an error would be generated if this cannot be done, but none of that is done, so changing the default version selected by this package is very likely going to get you in trouble.

Also you have made it so that the version that you specify is completely ignored when webhooks are defined. This is also unexpected.

I really prefer to leave which version to use up to this package. If you need to do an override and you know what you are doing, then you can add a process_apispec handler and modify the generated spec as you need.

Thanks for the quick response!

The main aim I'm trying to get with this PR it to allow me to generate a 3.1.0 OpenAPI spec. APIFairy does support generating a 3.1.0 spec, however you need to use the @webhook decorator to do so. The projects I work on don't require the webhook decorator, however I need to create a 3.1.0 spec since I need to use some tools from the OpenAPI eco-system to parse, lint and test the generated spec. These tools only work with OpenAPI version 3.1.0 and above. Maybe we can just provide a way for users to choose between 3.0.3 and 3.1.0 since APIFairy supports both versions?

[miguelgrinberg]

Wouldn't the process_apispec solution I mentioned above work?

        @apifairy.process_apispec
        def edit_apispec(apispec):
            apispec['openapi'] = '3.1.0'
            return apispec

[Danthewaann]

The openapi_version you provide to the APISpec class in /src/apifairy/core.py is actually used by the apispec package to generate an appropriate openapi doc for that version. Changing the openapi property in the process_apispec decorator will only change that property and nothing else. The rest of the generated document will not accurately reflect a 3.1.0 OpenAPI spec since there was breaking changes made in this version that are not compatible with 3.0.x versions.

[miguelgrinberg]

Oh okay. I don't think I remember seeing different output between 3.0.3 and 3.1.0, but it does look like there are some changes in the 3.1 serialization format, so I now understand the problem better.

Okay, I'm rethinking my answer from above. Let's add the version option, but with the following changes:

• If the user selects a version, that is the version that is generated. If the user selected version is incorrect for the features in their app, then that should trigger an error. Hopefully the apispec package helps with this.
• If the user does not select version, then we continue to choose the oldest compatible version.
• If the user selects a version that the apispec package does not recognize, that's also an error.

Does this sound better?

[Danthewaann]

Yes that sounds good 👍. I'll push up some more changes to the PR this week when I'm able to.

[Danthewaann]

@miguelgrinberg I think I'm happy enough with the recent changes. I would appreciate any more feedback or suggestions you might have!

[Danthewaann]

@miguelgrinberg Do you have any more feedback for this PR? If not, are you happy enough to merge it and publish a new version of APIFairy?

[miguelgrinberg]

Thanks! Release as version 1.5.0.