0

We have a running Redoc server, which includes a bunch on yaml files with api specifications. However, a couple of neccesary yaml files are not on the local (let's call it RedocServer) machine.

Those remote files are accessible through aspnet-webapi service (WebApiServer).

So, let's say, to get one of those files, we use refernce in the index.yaml file:

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

If ApiDoc.yaml itself has no refences, there is no problem for WebApiServer to simply return a string using a method like that:

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

However, in our case, that ApiDoc.yaml has some huge, nested references to another files inside it. Something like that, implying that referenced objects have references inside them:

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"

If WebApiServer returns a string like that, RedocServer will probably just try to resolve these references with RedocServer files. But we obviously want to make sure that refernces will be resolved on the WebApiServer side.

So, the question is, how to properly return that ApiDoc.yaml without breaking any references?

We cannot resolve references manually because objects are huge and deeply nested. OpenApi.net, which we tried to use, still isn't able to resolve remote references automatically, and also doesnt't seem to be able to work with files without "info" and "openapi:3.0.0" part in it.

Vladislav
  • 1
  • 1
  • Unrelated to your question, but you are mixing up OpenAPI 2.0 and 3.0 syntax - `consumes` and `produces` are OAS2 keywords, whereas `requestBody` and `content` are OAS3 keywords. Make sure to use the syntax that matches the OAS version you use. – Helen Apr 27 '20 at 07:21
  • Thanks, @Helen, I'll take note of that. Seems like Redoc is pretty tolerate of that kind of mistakes. – Vladislav Apr 27 '20 at 07:53

1 Answers1

0

As it turns out, Redoc automatically parses remote references, replacing local path in urls with remote url.

So simply put: you can just return a string or file like that, and everything should be working all right.

Vladislav
  • 1
  • 1