无法设置招摇 - 无法读取未定义的属性“参数”

Question

在我的 node.js 应用程序中设置 swagger 时遇到问题。我使用swagger-jsdoc 和swagger-ui-express 来创建文档。这是版本

“swagger-jsdoc”：“3.5.0”，“swagger-ui-express”：“4.1.3”

下面是我传递给 swagger-jsdoc 的配置。

openapi: 3.0.0
info:
  description: test
  version: 3.0.0
  title: U-CRM api documentation
  termsOfService: http://swagger.io/terms/
servers:
  - url: 'https://localhost:5000'
    description: Local server
tags:
- name: U-CRM
  description: CRM for university
components:
  parameters:
    $ref: 'components/parameters/index.yml'
  schemas:
    $ref: 'components/schemas/index.yml'
paths:
  $ref: '#/paths/index.yml'

毕竟，我得到一个错误

无法读取未定义的属性“参数”

实际上，当我仔细阅读 swagger 文档时，这让我感到惊讶。 可能是什么问题？

Answer 1

OpenAPI 不支持$ref无处不在。 $ref 只能在 OpenAPI Specification 明确声明字段的值可以是“引用对象”的特定位置使用。

例如，$ref 不允许直接在 paths、components/parameters 和 components/schemas 下 - 您只能引用单个路径、参数和架构。

您的示例的正确版本是：

paths:
  /foo:
    $ref: '#/paths/index.yml#/~1foo'  # $ref to root node `/foo` in `paths/index.yml`
  /bar:
    $ref: '#/paths/index.yml#/~1bar'  # $ref to root node `/bar` in `paths/index.yml`

components:
  parameters:
    param1:
      $ref: 'components/parameters/index.yml#/param1'
    param2:
      $ref: 'components/parameters/index.yml#/param2'
  schemas:
    schema1:
      $ref: 'components/schemas/index.yml#/schema1'
    schema2:
      $ref: 'components/schemas/index.yml#/schema2'

如果您想在随机位置使用$ref，则必须使用可以解析任意 $refs; 的解析器/工具预处理您的定义；这将为您提供一个有效的 OpenAPI 文件，该文件可与符合 OpenAPI 的工具一起使用。一个这样的预处理工具是json-refs，你可以找到一个预处理的例子here。