OpenAPI Emitter: Response should respect @useRef

[mcchrish]

Clear and concise description of the problem

namespace Pet Service {
  @get
  op get(@path petId: string): CustomResponse;
}

@useRef("https://example.com/example.yml")
model CustomResponse {
  @statusCode
  status: 200;
}

Should compile to:

      responses:
        '200':
          $ref: 'https://example.com/example.yml'

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[markcowl]

p2

[sarangan12]

Playground Link

[sarangan12]

In the package openapi3, the following test will succeed.

it("set external reference model", async () => {
  const [{ Foo }, diagnostics] = await runner.compileAndDiagnose(`
        @test @useRef("https://example.com/example.yml")
        model Foo {
          @statusCode
          status: 200;
        }
      `);
  expectDiagnosticEmpty(diagnostics);
  strictEqual(getRef(runner.program, Foo), "https://example.com/example.yml");
});

So, there is no problem in setting the reference. The reference is set correctly. But, it is not written to the output. i.e. this test will error out:

describe("openapi3: useRef decorator", () => {
  it("adds a ref extension to a model", async () => {
    const oapi = await openApiFor(`
      @test @useRef("../common.json#/definitions/Foo")
      model Foo {
        @statusCode
        status: 200;
        name: string;
      }
      @get op get(): Foo;
    `);
    ok(oapi.paths["/"].get);
    strictEqual(oapi.paths["/"].get.responses["200"]["$ref"], "../common.json#/definitions/Foo"); // <--- Will error out here
  });
});

[sarangan12]

Code Complete

[chrisradek]

Closed by #3894

[wingfaic]

Should $ref be emitted without siblings? (specifically the built in response descriptions which can't be removed)

Otherwise it'll cause this default spectral rule to fail https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#no-ref-siblings.

Example

@useRef("https://example.com")
model Error {
  @statusCode _: 500;
}

@useRef("https://example.com")
model Response {}

@route("/get")
op get(): Response | Error;

0.59.0-dev.4 Currently outputs

get:
  operationId: get
  parameters: []
  responses:
    '200':
      description: The request has succeeded.
      $ref: https://example.com
    '500':
      description: Server error
      $ref: https://example.com

But should be

get:
  operationId: get
  parameters: []
  responses:
    '200':
      $ref: https://example.com
    '500':
      $ref: https://example.com