openapi3 convert - make component responses models

[baywet]

Clear and concise description of the problem

Currently the import tool does not create models for component responses.

So the following OpenAPI description

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
paths:
  "/endpoint":
    get:
      summary: Example endpoint
      responses:
        '200':
          description: Successful response
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    TooManyRequests:
      description: The request was rejected because a rate limit was exceeded.
      headers:
        Retry-After:
          description: The minimum number of seconds to wait before retrying. This header
            is returned when the server has computed a retry delay and may be
            omitted for 429 responses that require user action.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: A human-readable message providing more details about the error.

Results in the following typespec definition

@route("/endpoint)
@get
op endpoint(): void | {
 @statusCode statusCode: 429;
 @header("Retry-After") @minValue(1) RetryAfter?: integer;
 @body body: ErrorResponse;
}

While this works for a single operation, it results in a lot of duplication when a lot of operations refer to the same component response, and it'd be easier to emit a model for the response like so

model ErrorResponseBody {
  @statusCode statusCode: 429;
  @header("Retry-After") @minValue(1) RetryAfter?: integer;
  @body body: ErrorResponse;
}

@route("/endpoint)
@get
op endpoint(): void | ErrorResponseBody

Note: there's a chance of collision between the component response name, and component schemas, so the import tool need to test for and guard against that as well.

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.

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: The service is temporarily unavailable. Please try again later. (Request id: E7B7:80E03:263B:3152:6A8713F4)

[github-actions]

🎯 Issue Triage

Feature request for the OpenAPI3-to-TypeSpec converter to emit named models for components/responses entries, reducing duplication when multiple operations reference the same component response.

Category: Feature Request

Area: openapi3:converter

🔍 Analysis

• Currently, components/responses referenced via $ref are inlined at each operation, which causes duplication across operations sharing the same response.
• The request is to emit a named TypeSpec model per component response (e.g., ErrorResponseBody) and reference it from each operation.
• The author correctly notes a potential name collision between components/responses and components/schemas entries — the converter must guard against this (e.g., by applying a suffix or checking the existing namespace).
• Affected package: @typespec/openapi3 converter.
• Similar work has been done for component schemas already; this extends that pattern to responses.

📝 Suggested next steps

• Identify where the converter resolves $ref to components/responses and currently inlines the response.
• Add logic to emit a named model for each entry in components/responses, with an appropriate name (handling collision with components/schemas).
• Reference the generated model in each operation that uses the $ref.
• Add unit tests covering: single-use response (still emits model), multi-use response (shared model), name collision with a schema.

Generated by Agentic Triage