无法引用在 Swagger 的单独文件中定义的组件架构
Cannot reference a component schema defined in a separate file in Swagger
我有以下 api 文档:
swagger: "3.0"
info:
version: 0.0.1
title: Test API
paths:
/users:
get:
summary: Get all registered users
produces:
- application/json
responses:
200:
description: Users successfully returned
403:
description: User not authorised to call this API
schema:
$ref: 'components.yaml#/components/schemas/AuthError'
其中 AuthError 模式在名为 components.yaml:
的单独 yaml 文件中定义
components:
schemas:
AuthError:
type: object
properties:
error:
type: sting
description: Error message
以及 Swagger 配置:
const swaggerDefinition = {
info: {
title: 'FlexiWAN REST API documentation',
version: '1.0.0',
description: 'This is the REST API for FlexiWAN management',
},
components: {},
host: 'local.flexiwan.com:3443',
basePath: '/api',
securityDefinitions: {
JWT: {
type: 'apiKey',
in: 'header',
name: 'Authorization',
description: "",
}
}
};
const options = {
swaggerDefinition,
apis: ['./swagger/**/*.yaml'],
};
const swaggerSpec = swaggerJSDoc(options);
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
但是当我尝试访问 Swagger UI 时出现以下错误:
路径解析器错误./users.get.responses.403.schema.$ref
无法解析引用:尝试在没有 basePath 的情况下解析相对 URL。路径:'components.yaml' 基本路径:'undefined'
我在这里错过了什么?
所以我设法使用 this great resource:
解决了这个问题
我所要做的就是在 API 文档文件的末尾添加对组件的引用,并相应地更改架构引用:
403:
description: User not authorised to call this API
schema:
$ref: '#components/schemas/AuthError'
components:
$ref: './components.yaml'
我有以下 api 文档:
swagger: "3.0"
info:
version: 0.0.1
title: Test API
paths:
/users:
get:
summary: Get all registered users
produces:
- application/json
responses:
200:
description: Users successfully returned
403:
description: User not authorised to call this API
schema:
$ref: 'components.yaml#/components/schemas/AuthError'
其中 AuthError 模式在名为 components.yaml:
的单独 yaml 文件中定义components:
schemas:
AuthError:
type: object
properties:
error:
type: sting
description: Error message
以及 Swagger 配置:
const swaggerDefinition = {
info: {
title: 'FlexiWAN REST API documentation',
version: '1.0.0',
description: 'This is the REST API for FlexiWAN management',
},
components: {},
host: 'local.flexiwan.com:3443',
basePath: '/api',
securityDefinitions: {
JWT: {
type: 'apiKey',
in: 'header',
name: 'Authorization',
description: "",
}
}
};
const options = {
swaggerDefinition,
apis: ['./swagger/**/*.yaml'],
};
const swaggerSpec = swaggerJSDoc(options);
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
但是当我尝试访问 Swagger UI 时出现以下错误:
路径解析器错误./users.get.responses.403.schema.$ref 无法解析引用:尝试在没有 basePath 的情况下解析相对 URL。路径:'components.yaml' 基本路径:'undefined'
我在这里错过了什么?
所以我设法使用 this great resource:
解决了这个问题我所要做的就是在 API 文档文件的末尾添加对组件的引用,并相应地更改架构引用:
403:
description: User not authorised to call this API
schema:
$ref: '#components/schemas/AuthError'
components:
$ref: './components.yaml'