无法设置 swagger - 无法读取未定义的属性“参数" [英] Can't setup swagger - Cannot read property 'parameters' of undefined

问题描述

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

I am having a problem with setting up the swagger into my node.js application. I am using swagger-jsdoc and swagger-ui-express for creating documentation. Here are the versions

"swagger-jsdoc": "3.5.0", "swagger-ui-express": "4.1.3"

"swagger-jsdoc": "3.5.0", "swagger-ui-express": "4.1.3"

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

Below is the configs, which I pass to 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'

毕竟，我得到了一个错误

After all, I get an error

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

Cannot read property 'parameters' of undefined

实际上，这让我感到惊讶，因为我仔细阅读了 swagger 文档.可能是什么问题?

Actually, it is surprising to me, as I read swagger docs carefully. What could be the problem?

推荐答案

OpenAPI 不支持 $ref 无处不在.$ref 只能在 OpenAPI 规范明确规定字段的值可以是引用对象".

OpenAPI does not support $ref everywhere. $ref can only be used in specific places where the OpenAPI Specification explicitly states that the value of a field can be a "Reference Object".

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

For example, $ref is not allowed directly under paths, under components/parameters and components/schemas - you can only reference individual paths, parameters and schemas.

您的示例的正确版本是:

The correct version of your example is:

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，则必须使用可以解析任意 $ref 的解析器/工具对定义进行预处理；这将为您提供一个有效的 OpenAPI 文件，该文件可与符合 OpenAPI 的工具一起使用.一个这样的预处理工具是json-refs，你可以找到一个预处理的例子此处.

If you want to use $ref in random places, you'll have to pre-process your definition using a parser/tool that can resolve arbitrary $refs; this will give you a valid OpenAPI file that can be used with OpenAPI-compliant tools. One such pre-processing tool is json-refs, you can find an example of pre-processing here.

这篇关于无法设置 swagger - 无法读取未定义的属性“参数"的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！