microsoft / microsoft/typespec
openapi3 convert - make component responses models
- 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
Assessment
This issue has not been assessed yet.