时间：2019-04-01 标签：c#swagger openapi erronous refs when nested classes

Posted 2023-03-31

【中文标题】时间：2019-04-01 标签：c#swagger openapi erronous refs when nested classes

【英文标题】：c# swagger openapi erronous refs when nested classes

【发布时间】：2020-04-29 09:41:58

【问题描述】：

在将我的 OpenAPI 上传到 Azure API 管理时，我的 API 的默认 swagger 生成会出现错误。使用 Swagger Editor 进行测试，发现如下错误：

“$ref 值必须是符合 RFC3986 的百分比编码 URI”。

看来我的嵌套类数据类型转换为：

$ref: >-
              #/components/schemas/Namespace.Class+NestedClass

我猜是“+”号需要删除或编码。 关于如何实现这一点的任何建议？

【问题讨论】：

Azure 给你什么错误？虽然 OAS3 确实不允许在模式名称中使用 +，但可能存在与 Azure's OAS import limitations 相关的其他问题。另外，您使用什么工具来生成 API 定义 - Swashbuckle、Swagger-Net 等等？

Azure 错误：解析错误：组件“模式”中的键“Namespace.Class+NestedClass”必须匹配正则表达式“^[a-zA-Z0-9\.\ -_]+$'。 [＃/成分]。 Swagger 编辑器错误：components.schemas.Namepsace.Class.properties.NestesClass.items.$ref 的语义错误 $ref 值必须是符合 RFC3986 的百分比编码 URI。 API 定义由 Swashbuckle.AspNetCore 生成。

这是一个 Swashbuckle 问题，它会生成带有不受支持字符的架构名称（在这种情况下 - +）。在github.com/domaindrivendev/Swashbuckle.AspNetCore/issues

提出问题

【参考方案1】：

我在尝试使用 api 管理发布服务时遇到了类似的问题。

解析错误：组件“模式”中的键“Namespace.Class+NestedClass”必须匹配正则表达式“^[a-zA-Z0-9.-_]+$”。 [#/组件]

在我的情况下，使用自定义架构 ID 并替换导致错误的字符解决了问题：

services.AddSwaggerGen(options =>

    options.CustomSchemaIds(type => type.FullName.Replace("+", "_"));
);