问题标签 [redoc]

我正在使用带有Redoc的 Swashbuckle来记录我的 ASP.NET Core 2.2 API。现场 ReDoc 演示在顶部有一组部分（例如“介绍”），其中包含一些自定义 html。我想在我的 API 中生成类似的部分，但不知道该怎么做。

基本上我有：

然后：

我已经浏览了 intellisense 选项，以及 Swashbuckle自述文件和wiki，但找不到生成此类部分的方法。

将 HTML 部分添加到基于 Swashbuckle.AspNetCore.ReDoc 的文档开头的方法是什么？

我的 API 文档变得非常大，我想知道是否可以将openapi.yml文件分成单独管理的块，而不是将它们全部合二为一并让 reDoc（或其他一些工具）将它组合起来，然后生成 HTML 站点。

我正在尝试使用 redoc 加载 json 文件。该文件托管在另一台服务器上。我收到此错误：

http://www.whatever-server.com/swagger/vs/swagger.json已被 CORS 策略阻止：请求的资源上不存在“Access-Control-Allow-Origin”标头。

由于该文件托管在另一台服务器上，因此我无法在该服务器上添加该标头。我无权访问它。我尝试从我的服务器而不是浏览器请求资源，但是我无法解析 json 文件中的所有引用 $ref ......有什么我能做的，或者是唯一的解决方案来询问这些人添加该标头的任何服务器？

谢谢

API平台版本： 1.2

这是我当前的 api_platform 配置文件：

启用 ReDoc 时出现此错误：

通过Swashbuckle.AspNetCore.Annotations将 ReDoc的 x-code-samples添加到swagger.json的最佳方法是什么？

编辑（2019 年 3 月 30 日）

我希望这是一个更好的解释。Swashbuckle.AspNetCore 中有一种方法可以将内容添加到生成的 swagger.json 中。

记录的内容 （来自 GitHub-Page 的示例）：

关于我试图实现的目标

我想做的是这样的：

我负责维护公司 API 文档。我们的 API 是用 ASP.NET 编写的。我最近切换到使用运行良好的 Swashbuckle 5.6.0。

我遇到的问题是这样的：

我们将数据模型分为 Post 数据和 Get 数据，例如WebAccountGetData.cs和WebAccountPostData.cs. 在创建 (POST) 和更新 (PUT) 时可以使用 Post 数据。

Post 数据类中的大多数（如果不是全部）字段都是可以为空的，当调用 API 方法时，存储的过程会返回错误消息，描述哪些字段丢失/需要。API 不处理必填字段。

使用可为空的字段意味着 Swashbuckle 不会在文档中添加必需标志。但是我们想根据使用的 Http 方法（Post/Put）来显示一个字段是否是必需的。

API 密钥是必需参数，因为它不能为空。

我知道我可以使用[Required]System.ComponentModel.DataAnnotations 命名空间中的属性，但这会将Required 标志应用于 POST 和 PUT 方法，这是我们不想要的。

理想情况下，我想使用自定义属性，我可以在其中指定 Post 或 Put 方法中是否需要字段。

然后像这样使用它：

有没有办法使用 customIDocumentFilter或将更改（如切换所需的标志）应用于模型字段的架构属性？还是在 Swashbuckle 中无法引用模型上的属性？IOperationFilterISchemaFilter

我正在使用redocindjango==2.0来记录一些djangoAPI。我注意到默认情况下，redoc 会自动命名端点，如下图左侧所示。很可能我不想使用生成的名称我想自定义名称。有redoc文档经验的人能给点建议吗？

我们的 ASP.NET Core 2.2 项目中有枚举，评论如下：

例如，我们像这样使用它们：

XML 注释在构建时生成，作为资源包含，并成为 OpenAPI 规范的一部分，如下所示：

最后，我们app.UseReDoc(c => ...)将 JSON 文件可视化。

问题：Theme枚举本身及其选项的 xml 注释都没有出现在我们文档的任何地方。它也不在 OpenAPI JSON 文档中（所以逻辑上它不会出现在 ReDoc 中）。

如何将此类文档放入您的 OpenAPI JSON，然后放入 ReDoc 页面？

对如何在 JSON 文档（使用 Swagger）中指示 OR 有疑问。

我不想发表评论，表明但想知道展示这一点的典型方式是什么？

假设我有以下内容：方法类型：PATCH

向 API 调用者显示其中一个字段是必需的，但同时输入这两个字段是可选的，有什么好方法？本质上是 XOR 或 OR

在 swagger redoc 中，我使用 markdown 创建了外部表，现在我需要使用 markdown 创建自己的下拉列表。你能帮帮我吗，我可以实现同样的。