Azure API管理导入OpenApi -解析错误:引用字符串格式无效

Question

我正在尝试将有效的OpenApi yaml文档导入Azure API管理。根据editor.swagger.io，该文档是有效的。

此文档是使用spec将多个yamls合并为一个文档自动生成的。

这是我的OpenApi文档的截断版本:

openapi: 3.0.2
info:
title: My API
version: "1.0"
servers:
- url: https://api.server.test/v1
paths:
"/account/{accountId}/billSummary":
get:
summary: get bill summary for account
description: |
Bill summary for account including bill statement breakdown
tags:
- Account bill summary
parameters:
- name: accountId
in: path
required: true
description: Account id
schema:
type: string
maximum: 12
pattern: "[0-9]+"
responses:
"400":
description: The accountId is invalid
content:
application/problem+json:
schema:
title: ProblemDetails
type: object
properties:
type:
type: string
format: uri
example: https://tools.ietf.org/html/rfc7231#section-6.5.4
title:
type: string
example: Not Found
status:
type: integer
example: 404
traceId:
type: string
format: uuid
example: 00-e1f13d1f98e0b9273e7ccbdf50376e7d-684a978b72c01f49-00
errors:
type: object
nullable: true
"404":
description: The account is not found
content:
application/problem+json:
schema:
$ref: "#/paths/~1account~1%7BaccountId%7D~1billSummary/get/responses/400/conten
t/application~1problem%2Bjson/schema"
"500":
description: An unexpected error occurred
content:
application/problem+json:
schema:
$ref: "#/paths/~1account~1%7BaccountId%7D~1billSummary/get/responses/400/conten
t/application~1problem%2Bjson/schema"

我的问题是404响应模式是对在400响应中定义的ProblemDetails对象的引用。

当我尝试导入它时，API管理抛出错误:

Parsing error(s): The reference string '/paths/~1account~1%7BaccountId%7D~1billSummary/get/responses/400/content/application~1problem%2Bjson/schema' has invalid format. [#/paths//account/{accountId}/billSummary/get/responses/404/content/schema] The reference string '/paths/~1account~1%7BaccountId%7D~1billSummary/get/responses/400/content/application~1problem%2Bjson/schema' has invalid format. [#/paths//account/{accountId}/billSummary/get/responses/500/content/schema]

我尝试了其他工具来合并我的yamls而不是spec，例如swagger-merge，它的输出是相同的。

我可以通过更改yaml -将ProblemDetails添加为组件来手动解决它，但这是不可取的，因为我试图将其作为发布管道的一部分自动化。

手动解决方法如下:

openapi: 3.0.2
info:
title: Self Service API
version: "1.0"
servers:
- url: https://api.server.test/v1
paths:
"/account/{accountId}/billSummary":
get:
summary: get bill summary for account
description: |
Bill summary for account including bill statement breakdown
tags:
- Account bill summary
parameters:
- name: accountId
in: path
required: true
description: Account id
schema:
type: string
maximum: 12
pattern: "[0-9]+"
responses:
"400":
description: The accountId is invalid
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetails"
"404":
description: The account is not found
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetails"
"500":
description: An unexpected error occurred
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetails"
components:
schemas:
ProblemDetails:
type: object
properties: 
type:
type: string
format: uri
example: https://tools.ietf.org/html/rfc7231#section-6.5.4
title:
type: string
example: Not Found
status:
type: integer
example: 404
traceId:
type: string
format: uuid
example: 00-e1f13d1f98e0b9273e7ccbdf50376e7d-684a978b72c01f49-00
errors:
type: object
nullable: true

Answer 1

我为此向微软提出了支持请求，显然这被认为是递归，这是不支持的。

递归:API管理不支持递归定义。例如，模式引用自己。

来源:https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions