Conformance with OAS 3.0.*

[AnyCPU]

I have trouble using Stripe OAS with OAS code generators, specifically in Go.

Let's take a look at an example of Stripe OAS below:

openapi: 3.0.0
paths:
  /v1/account:
    get:
      description: <p>Retrieves the details of an account.</p>
      operationId: GetAccount
      parameters:
        - description: Specifies which fields in the response should be expanded.
          explode: true
          in: query
          name: expand
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject

It belongs to a stripe specific feature like expandable objects - https://docs.stripe.com/api/expanding_objects.

But the deepObject style cannot represent arrays according to following info - https://swagger.io/specification/v3/#parameter-object.

There you can find some examples how styles are applied. A form style could have been used.

It was mentioned earlier there - https://github.com/stripe/openapi/issues/153.

And I understand that it is not a bug it is a feature, because you use a custom private code generator.

Also I guess that it is not possible to patch it simply like style: deepObject -> style: form, because, for instance, a stripe server will not accept it.

So that's why I think it would be nice to:

• update documentation, add more explicit statement about a conformance with OAS 3.0.*;
• add an OAS extension in case of expandable object.

For instance:

openapi: 3.0.0
paths:
  /v1/account:
    get:
      description: <p>Retrieves the details of an account.</p>
      operationId: GetAccount
      parameters:
        - description: Specifies which fields in the response should be expanded.
          explode: true
          in: query
          name: expand
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject
          x-vendor-style: stripe

It might allow to handle it more correctly in 3rd party code generators.

[jar-stripe]

@AnyCPU thanks for the suggestion here! We'll add it to our backlog for future discussion.