Support OpenAPI 3.1

[BorisBeast]

Are there any plans to support OpenAPI v3.1? If yes when can we expect it?

If nothing else it will allow exploded arrays for multipart/form-data requests which is the default behavior of MultipartParser. https://spec.openapis.org/oas/v3.1.0#fixed-fields-12

[tfranzel]

hi @BorisBeast, the plan is definitely there. imho SwaggerUI and openapi-generator are the main usages of spectacular and and the last time i looked they had not added support yet. i kind of waited for them to move first.

swagger-api/swagger-ui/issues/5891

OpenAPITools/openapi-generator/issues/9083

in any case, some of the new feature may take a while to implement as the move to JSON schema in the new specification has quite a few smaller and bigger implications.

[tfranzel]

small update:

• jsonschema, our validation dependency received an update to support Draft 2020-12 (required for 3.1)
• our whole test suite is green wrt. OpenAPI 3.1 validation (iff 3.0.3 is replaced with 3.1.0)
• SwaggerUI will add support in 4.x.x
• Redoc has added preliminary support
• openapi-generatorI'm not sure about their current state.

With all the changes in OpenAPI 3.1, I currently only see a potential issue with the change in semantics for readOnly/writeOnly (they are deferred to JSON Schema). Apart from that I don't see many roadblocks ahead.

That said, I decided to wait a little longer with adoption. Firstly, drf-spectacular is not very useful without a working ecosystem around it. Secondly, we do not simply implement OpenAPI without any context. We intentionally refrain from using certain valid constructions, which have shown to create problems with other tools. Not every valid schema will be properly handled by UIs or code generators. That practical aspect is very important to drf-spectacular and it's probably best to wait a bit longer until the dust has settled in the ecosystem.

[johnthagen]

That practical aspect is very important to drf-spectacular and it's probably best to wait a bit longer until the dust has settled in the ecosystem.

I'm excited for OpenAPI 3.1 but I too think it is pragmatic to wait a while for the rest of the ecosystem to catch up.

[raianul]

Hello @johnthagen

I am getting this error, any idea how to fix this?

so far my understanding its required OpenAPI 3.0.

[johnthagen]

@pranto157 No, I don't know what's going on there. Sorry.

[raianul]

@johnthagen -

I am using pydentic model for my code and was thinking to use my model schema as swagger response. So here is my full schema from pydentic model

{
   "title":"ExpressAccount",
   "description":"Schema for Merchant's account within stripe.",
   "type":"object",
   "properties":{
      "id":{
         "title":"Id",
         "type":"string"
      },
      "business_profile":{
         "$ref":"#/definitions/AccountBusinessProfile"
      },
      "capabilities":{
         "$ref":"#/definitions/AccountCapabilities"
      }
   },
   "required":[
      "id",
      "business_profile",
      "capabilities"
   ],
   "definitions":{
      "AccountBusinessProfile":{
         "title":"AccountBusinessProfile",
         "type":"object",
         "properties":{
            "mcc":{
               "title":"Mcc",
               "type":"string"
            },
            "name":{
               "title":"Name",
               "type":"string"
            },
            "support_address":{
               "title":"Support Address",
               "type":"string"
            },
            "support_email":{
               "title":"Support Email",
               "type":"string"
            },
            "support_phone":{
               "title":"Support Phone",
               "type":"string"
            },
            "support_url":{
               "title":"Support Url",
               "type":"string"
            },
            "url":{
               "title":"Url",
               "type":"string"
            }
         }
      },
      "AccountCapabilities":{
         "title":"AccountCapabilities",
         "type":"object",
         "properties":{
            "bancontact_payments":{
               "title":"Bancontact Payments",
               "type":"string"
            },
            "card_payments":{
               "title":"Card Payments",
               "type":"string"
            },
            "eps_payments":{
               "title":"Eps Payments",
               "type":"string"
            },
            "giropay_payments":{
               "title":"Giropay Payments",
               "type":"string"
            },
            "ideal_payments":{
               "title":"Ideal Payments",
               "type":"string"
            },
            "p24_payments":{
               "title":"P24 Payments",
               "type":"string"
            },
            "sepa_debit_payments":{
               "title":"Sepa Debit Payments",
               "type":"string"
            },
            "sofort_payments":{
               "title":"Sofort Payments",
               "type":"string"
            },
            "transfers":{
               "title":"Transfers",
               "type":"string"
            }
         }
      }
   }
}

So the "$ref":"#/definitions/AccountBusinessProfile" is getting error though the document is exists in the schema.

[tfranzel]

@pranto157 this issue is dedicated to OpenAPI 3.1. your issue is unrelated.

[Fares-Abubaker]

Hello all , @tfranzel

did you add the support for OpenAPI 3.1? and what about the Json Schema Draft 2020 ?

[tfranzel]

we released 0.27.0, which is the first version to support 3.1

I'm not exactly sure how to answer your second question @Fares-Abubaker. 3.1 was made to be JSON Schema compatible. So by definition if a schema is OpenAPI 3.1, it has to be JSON Schema compatible. The differences are small anyway and we only adapted what was conflicting with conformity.

Is there anything missing? I'll close this issue as I consider this resolved. If anything else is missing, please feel free to open a new issue.

[tfranzel]

We released 0.27.0 with basic OpenAPI 3.1 support.

For further feature requests regarding 3.1 features, please open a new issue.

[tu-pm]

Thanks @tfranzel for the hard work.

I'm playing around with the new OpenAPI 3.1 swagger from the latest release (drf-spectacular==0.27.2 and drf-spectacular-sidecar==2024.4.1) by setting 'OAS_VERSION': '3.1.0', in SPECTACULAR_SETTINGS and the Swagger UI page still displays this message:

Unable to render this definition

The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

What am I missing here?

[tfranzel]

The error msg implicitly states that 3.1 is not supported, only 2 and 3.0.x.

The next version of swagger UI, does support it though, as can be seen on their editor example page. I believe this version is still beta and thus not part of the sidecar at the moment.

You would need to find a cdn link with the proper version to make this work

On Wed, Apr 17, 2024, 10:48 tu-pm @.***> wrote:

Thanks @tfranzel https://github.com/tfranzel for the hard work.

I'm playing around with the new OpenAPI 3.1 swagger from the latest release (drf-spectacular==0.27.2 and drf-spectacular-sidecar==2024.4.1) by setting 'OAS_VERSION': '3.1.0', in SPECTACULAR_SETTINGS and the Swagger UI page still displays this message:

Unable to render this definition

The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

What am I missing here?

— Reply to this email directly, view it on GitHub https://github.com/tfranzel/drf-spectacular/issues/378#issuecomment-2060733217, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADHB2EPCR6ZU2NNUUEJMYR3Y5YZM3AVCNFSM44JJVRM2U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMBWGA3TGMZSGE3Q . You are receiving this because you were mentioned.Message ID: @.***>