You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If the implementation added a new field storage_size, Table in the #/components/schemas/ get updates.
Motivation
If there are "duplicated" schemas, such as Table in get /tables, post /tables andget /tables/{id}, some OpenAPI client generators generate separate types for each of duplicated schemas.
One example is openapi-typescript-codegen generating API client codes like below:
In this example, there are three unnamed structural types that represent Table.
Those three types have the exact same type and are "compatible" if the type system at the client-side supports structural typing.
TypeScript does, but Java not.
There is another problem.
Since those types have no name, it is a bit tricky to refer the types in a nominal manner.
(One may use ReturnType<func> and other utility types).
Users may reduce duplications by manually lifting the schemas into /components/schemas/Table and using $refs with it.
However, /components/schemas/Table are not updated by rspec-openapi.
Users need to update /components/schemas/ by themselves, which diminishes the value of rspec-openapi somewhat.
If the schema in /components/schemas gets updated automatically, it helps leverage OpenAPI files with client-generating tools with strong types.
The feature looks good to me. While it's hard for rspec-openapi to generate $ref by itself because of its design, when a human decides to carve out a $ref manually, it makes total sense to let rspec-openapi update it. I still have no good idea to fully automate it, but it seems like a good first step towards better $ref support.
It's a nitpick, but I guess this issue should be formatted like s/Summary/Proposal/ to make your point clear.
Summary
When rspec-openapi detects
$ref
in the existing item to be modified, rspec-openapi update the referenced item incomponents
section.Basic example
Let's say we have the openapi below, generated with rspec-openapi and modified manually to use
$ref
.If the implementation added a new field
storage_size
,Table
in the#/components/schemas/
get updates.Motivation
If there are "duplicated" schemas, such as
Table
inget /tables
,post /tables
andget /tables/{id}
, some OpenAPI client generators generate separate types for each of duplicated schemas.One example is openapi-typescript-codegen generating API client codes like below:
In this example, there are three unnamed structural types that represent
Table
.Those three types have the exact same type and are "compatible" if the type system at the client-side supports structural typing.
TypeScript does, but Java not.
There is another problem.
Since those types have no name, it is a bit tricky to refer the types in a nominal manner.
(One may use
ReturnType<func>
and other utility types).Users may reduce duplications by manually lifting the schemas into
/components/schemas/Table
and using$refs
with it.However,
/components/schemas/Table
are not updated by rspec-openapi.Users need to update
/components/schemas/
by themselves, which diminishes the value of rspec-openapi somewhat.If the schema in
/components/schemas
gets updated automatically, it helps leverage OpenAPI files with client-generating tools with strong types.Related issues
The text was updated successfully, but these errors were encountered: