microsoft / microsoft/typespec

openapi3 convert - make component responses models

Open
#11,734 2 comments 2 reactions 2 assignees Claimed by @copilot-swe-agent View on GitHub
feature lib:openapi openapi3:converter
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Clear and concise description of the problem

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

So the following OpenAPI description

```yaml
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

```typespec
@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

```typespec

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

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.