Support for OpenAPI Specification 3.1.0

[gk12277]

Hi, some time back OpenAPI Specification 3.1.0 was released which supports JsonSchema 2020-12 Draft by default. Would be great if support could be provided for this.

There are some major changes like null in type

phoneNumber:
 type: 
  - "null"
  -  number

[mirecl]

Now, OpenAPI Specification 3.1.0 support Security Scheme Object type mutualTLS

[ratermir]

Very awaited feature, to be able to use 3.1 features like comments on "$ref", null values (mentioned here) ... etc

[pauldraper]

For reference, 3.1.0 was released 7 months ago (Feb 2021).

[DepickereSven]

FYI: it's in the short term roadmap but that's for Swagger Core and Swagger Parser You can read more here https://github.com/swagger-api/swagger-parser/issues/1535#issuecomment-936707841

It seems release 4.x.x of the UI is also preparing for OpenApi 3.1

Moving to v4 will allow us to further evolve SwaggerUI/SwaggerEditor in order to use the latest features from React (Hooks, Contexts, etc...) and prepare for OpenApi 3.1 adoption.

More information can be found here: https://swagger.io/blog/api-design/what%E2%80%99s-ahead-for-swaggerui-v4-and-swaggereditor-v4/

Github release tag: https://github.com/swagger-api/swagger-editor/releases/tag/v4.0.0-rc.0

[Stokestack]

I just tried V4 and it still balks at OpenAPI 3.1 documents.

[UkonnRa]

Any update?

[dimaqq]

Poke 🙏🏼

[JoshuaVSherman]

This is preventing up from moving to 3.1 as well, and there is a nice feature with postman that will allow importing of 3.1 openapi directly therefore we won't need to maintain both sets of api docs anymore, hope this can get finished soon, thanks for all you do!

[frankkilcommins]

Hi folks, here's a general update on the work towards OpenAPI 3.1 support across the tool suite: Swagger support for OpenAPI 3.0 and OpenAPI 3.1

[jashanbhullar]

I am a bit confused. The swagger editor still doesn't support 3.1 but there's an editor at https://editor-next.swagger.io/ which apparently does support 3.1 but I checked the exclusiveMaximum keyword and it's not working as expected...is there something I am missing?

[char0n]

Hi @jashanbhullar,

SwaggerEditor is now released under two major release channels:

1. SwaggerEditor@4 - released from master branch and deployed at https://editor.swagger.io/
2. SwaggerEditor@5 - released from next branch and deployed at https://editor-next.swagger.io/

Only SwaggerEditor@5 supports OpenAPI 3.1.0. SwaggerEditor@4 will not receive OpenAPI 3.1.0 support and is considered legacy at this point. The plan is to continually migrate fully to SwaggerEditor@5 and deprecate the SwaggerEditor@4 in future.

---

but I checked the exclusiveMaximum keyword and it's not working as expected...is there something I am missing?

We would need more information. What particular about the keyword doesn't work? The linting, rendering or other? What is the definition you used?

[jashanbhullar]

For type number you can select the bounds by using minimum and maximum or by using exclusiveMinimum and exclusiveMaxmimum. Docs here

By using minimum and maximum the editor shows the error as:

While with exclusiveMaximum and exclusiveMinimum, it doesn't throw a validation error and sends the request to the backend

Same behaviour is observed in swagger 3.0 and in the editor https://editor.swagger.io/ so I guess this has always been there.

The syntax of exclusiveMaximum and exclusiveMinimum has also changed in 3.1. Source

Check the spec below

openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
paths:
  /:
    get:
      summary: Read Root
      operationId: read_root__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /number-with-no-equal:
    get:
      summary: Read Item
      operationId: read_item_number_with_no_equal_get
      parameters:
        - name: num
          in: query
          required: true
          schema:
            type: integer
            exclusiveMaximum: 100
            exclusiveMinimum: 0
            description: Enter a number between 0 and 100
            title: Num
          description: Enter a number between 0 and 100
          example: 1
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                properties:
                  detail:
                    items:
                      properties:
                        loc:
                          items:
                            anyOf:
                              - type: string
                              - type: integer
                          type: array
                          title: Location
                        msg:
                          type: string
                          title: Message
                        type:
                          type: string
                          title: Error Type
                      type: object
                      required:
                        - loc
                        - msg
                        - type
                      title: ValidationError
                    type: array
                    title: Detail
                type: object
                title: HTTPValidationError
  /number-with-equal:
    get:
      summary: Read Item
      operationId: read_item_number_with_equal_get
      parameters:
        - name: num
          in: query
          required: true
          schema:
            type: integer
            maximum: 100
            minimum: 0
            description: Enter a number between 0 and 100
            title: Num
          description: Enter a number between 0 and 100
          example: 1
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                properties:
                  detail:
                    items:
                      properties:
                        loc:
                          items:
                            anyOf:
                              - type: string
                              - type: integer
                          type: array
                          title: Location
                        msg:
                          type: string
                          title: Message
                        type:
                          type: string
                          title: Error Type
                      type: object
                      required:
                        - loc
                        - msg
                        - type
                      title: ValidationError
                    type: array
                    title: Detail
                type: object
                title: HTTPValidationError
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            properties:
              loc:
                items:
                  anyOf:
                    - type: string
                    - type: integer
                type: array
                title: Location
              msg:
                type: string
                title: Message
              type:
                type: string
                title: Error Type
            type: object
            required:
              - loc
              - msg
              - type
            title: ValidationError
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

[char0n]

@jashanbhullar thanks for clarification. You're steps of reproduction have been extracted into separate issue: https://github.com/swagger-api/swagger-ui/issues/9134. Simply said, SwaggerUI contains JSON Schema Draft 4/5 related primitive value validation. This validation needs to take into account that in OpenAPI 3.1.0 the used schema version is JSON Schema 2020-12.

[char0n]

@jashanbhullar hopefully I've removed the v4 vs v5 confusion in https://github.com/swagger-api/swagger-editor/pull/4367.

[char0n]

Closing this issue. The OpenAPI 3.1.0 support landed in SwaggerEditor@5. More info in https://github.com/swagger-api/swagger-editor/issues/2638#issuecomment-1679354080

[guyluz11]

It shows not supported https://editor.swagger.io/?url=https://raw.githubusercontent.com/Sensibo/sensibo.github.io/master/sensibo.openapi.yaml

[guyluz11]

I think this is the old editor editor.swagger.io --> editor-next.swagger.io The editor-next does not show the error

[char0n]

Here is an excerpt from the main README file explaining the situation:

https://github.com/swagger-api/swagger-editor/blob/master/README.md