无法设置 Swagger - 无法读取未定义的属性'parameters'

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'

毕竟，我得到了一个错误

无法读取未定义的属性"parameters">

事实上，这让我很惊讶，因为我仔细阅读了swagger文档。可能是什么问题？

Answer 1

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

例如，$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就是这样一个预处理工具，您可以在这里找到预处理的示例。