OpenApi (Redoc) 远程（网络）嵌套引用答案

【问题标题】：OpenApi (Redoc) remote (network) nested referencesOpenApi (Redoc) 远程（网络）嵌套引用
【发布时间】：2020-05-18 04:54:12
【问题描述】：

我们有一个正在运行的 Redoc 服务器，其中包含一堆带有 api 规范的 yaml 文件。但是，一些必要的 yaml 文件不在本地（我们称之为 RedocServer）机器上。

可以通过 aspnet-webapi 服务 (WebApiServer) 访问这些远程文件。

因此，假设要获取其中一个文件，我们在 index.yaml 文件中使用引用：

paths: 
  /api/1:
    $ref: "https:/some-address/ApiDoc.yaml"

如果 ApiDoc.yaml 本身没有引用，那么 WebApiServer 可以使用类似的方法简单地返回一个字符串：

[HttpGet]
public string GetApiDoc()
{
      var directoryPath = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
      var filePath = Path.Combine(directoryPath, "ApiDoc.yaml");
      return File.ReadAllText(filePath);
}

但是，在我们的例子中，ApiDoc.yaml 包含对其中其他文件的一些巨大的嵌套引用。类似的东西，暗示被引用的对象内部有引用：

post:
  tags:
    - Test
  summary: Test
  operationId: Test
  consumes:
  - application/json
  produces:
  - application/json
  requestBody:
    content:
      application/json:
        schema:
          $ref: "../ApiDoc2.yaml#/components/schemas/ApiRequest"
  responses:
    200:
      description: OK
      content:
        application/json:
          schema:
            $ref: "../ApiDoc3.yaml#/components/schemas/ApiResponse"

如果 WebApiServer 返回类似的字符串，RedocServer 可能会尝试使用 RedocServer 文件解析这些引用。但我们显然希望确保在 WebApiServer 端解析引用。

那么，问题是，如何在不破坏任何引用的情况下正确返回该 ApiDoc.yaml？

我们无法手动解析引用，因为对象很大且嵌套很深。我们尝试使用的 OpenApi.net 仍然无法自动解析远程引用，而且似乎也无法处理没有“info”和“openapi:3.0.0”部分的文件。

【问题讨论】：

与您的问题无关，但您混淆了 OpenAPI 2.0 和 3.0 语法 - consumes 和 produces 是 OAS2 关键字，而 requestBody 和 content 是 OAS3 关键字。确保使用与您使用的 OAS 版本匹配的语法。
谢谢@Helen，我会注意的。似乎 Redoc 可以容忍这种错误。

标签： c# asp.net-web-api openapi redoc

【解决方案1】：

事实证明，Redoc 会自动解析远程引用，将 url 中的本地路径替换为远程 url。

简单地说：你可以像这样返回一个字符串或文件，一切都应该正常工作。

【讨论】：