Redocly/redoc

Nullable support in `oneOf` operator

开放

#1,303 创建于 2020年6月17日

 (3 条评论) (1 个反应) (0 位负责人)TypeScript (2,272 个派生)batch import
Type: Enhancementhelp wanted

仓库指标

星标
 (21,877 个星标)
PR 合并指标
 (PR 指标待抓取)

描述

This is feature request.

Currently, redoc@2.0.0-rc.30 can show nullable: true field(s) on properties like below: image This is great !!

I have API requests/responses that uses oneOf operator, and some of schemas used in oneOf is nullable: true like below:

   Foo:
      oneOf:
        - $ref: "#/components/schemas/Foo1"
        - $ref: "#/components/schemas/Foo2"
    Foo1:
      type: object
      properties: ...
    Foo2:
      type: object
      nullable: true
      properties: ...

I think this is valid schema definition to express object could be null, according to OpenAPI 3.0 specs.

OpenAPI 3.0 does not have an explicit null type as in JSON Schema, but you can use nullable: true to specify that the value may be null. https://swagger.io/docs/specification/data-models/data-types/#null

So, it would be great if ReDoc can render such objects as nullable.

UI Suggestions

image

Example OpenAPI file

openapi: "3.0.0"
info:
  version: "1.2.3"
  title: "My API"
paths:
  /foo:
    post:
      operationId: postFoo
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Foo"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Foo"
  /bar:
    post:
      operationId: postBar
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Foo2"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Foo2"

components:
  schemas:
    Foo:
      oneOf:
        - $ref: "#/components/schemas/Foo1"
        - $ref: "#/components/schemas/Foo2"
    Foo1:
      type: object
      properties:
        foo1:
          type: string
          nullable: true
        bar:
          type: object
          nullable: true
          properties:
            x:
              type: int
            y:
              type: int
    Foo2:
      type: object
      nullable: true
      properties:
        bar:
          type: string
          nullable: true

贡献者指南