Swagger UI - 外部 JSON 模式文件的问题答案

【问题标题】：Swagger UI - Issue with external JSON schema filesSwagger UI - 外部 JSON 模式文件的问题
【发布时间】：2021-10-20 14:14:29
【问题描述】：

我使用 Swagger 设计 API，并使用 Swagger UI 在我们的公司 API 设计网站上显示它们。我有一个 JSON 文件，其中包含一个 JSONSCHEMA，其中包含我想在多个 SWAGGER 文件中使用的每个变量。

例如，假设 foo.json 文件包含以下架构：

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "fooooo",
    "version": "2021_11",
    "type": "object",
    "definitions": {
        "EligibilityNotification": {
            "type":"object",
            "properties": {
                "code": {
                    "type": "string"
                },
                "label": {
                    "type": "string"
                }
            }
        }
    }
}

我有以下招摇文件：

components:
   NotificationGroup:
      type: object
      properties:
        eligibilityNotifications:
          type: array
          items:
            $ref: '../JSONSchemas/foo.json#/definitions/EligibilityNotification'

相对路径是正确的，我在创建主题之前仔细检查了它。

当我通过“OpenAPI SwaggerUI preview”Visual Studio Code 的插件浏览 swagger 时，我在本地遇到以下问题：

“未知类型：object,null”

【问题讨论】：

foo.json 中的EligibilityNotification 模式是否指定"type":"object" 或"type": ["object", "null"]？后一种语法仅在 OpenAPI 3.1 中受支持，但在 3.0 中不受支持。

标签： json swagger swagger-ui jsonschema

【解决方案1】：

components 的定义似乎不正确：对于 OpenAPI 3.0 规范，它应该包括 schemas section；对于 OpenAPI 2.0，它应该命名为 definitions。

您可能还想安装 OpenAPI (Swagger) Editor 扩展来验证规范。

这是 OpenAPI 3.0 的一个工作示例：

openapi: 3.0.0
info:
  version: 1.0.0
  title: Sample API
  description: A sample API to illustrate OpenAPI concepts

paths:
  /notifications:
    post:
      description: Returns notifications
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  notifications:
                    $ref: "#/components/schemas/NotificationGroup"

components:
  schemas:
    NotificationGroup:
      type: object
      properties:
        eligibilityNotifications:
          type: array
          items:
            $ref: "../JSONSchemas/foo.json#/definitions/EligibilityNotification"

渲染如下（我使用Swagger Viewer进行渲染）：

如果您想使用 OpenAPI 2.0，以下是 swagger: "2.0" 规范的另一个工作示例：

swagger: "2.0"
info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
  - https

paths:
  /notifications:
    post:
      summary: Returns notifications
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            properties:
              notifications:
                $ref: "#/definitions/NotificationGroup"

definitions:
  NotificationGroup:
    properties:
      eligibilityNotifications:
        type: array
        items:
          $ref: "../JSONSchemas/foo.json#/definitions/EligibilityNotification"

【讨论】：