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
PR #1531 introduces the extensions field to object types, but it doesn't seem like this data even if specified is used for anything at the moment. At minimum, it'd be useful to have this data included in the generated OpenAPI spec.
Why would it be useful?
We use the OpenAPI spec to dynamically generate forms to interact with the APIs. Sometimes, we want to add additional metadata that's not strictly necessary for the API itself, but is useful to other tooling. An example of this might be the grouping of multiple properties into a fieldset, e.g. something like:
In this case, a downstream tool might look at the fieldsets extension and deduce that the fields name, age, and shoesize should belong to a fieldset called Personal information, and the field address should belong to another fieldset called Contact information. What a fieldset is, or how to interpret this schema, is entirely up to that tool and has nothing to do with Fern.
Describe the solution (optional)
The OpenAPI spec allows for schema objects to use specification extensions. I propose that the extensions object should (by default) generate corresponding specification extensions in the generated OpenAPI spec. In the aforementioned example, the generated OpenAPI spec might have something like the following in its schema:
Problem description
PR #1531 introduces the
extensions
field to object types, but it doesn't seem like this data even if specified is used for anything at the moment. At minimum, it'd be useful to have this data included in the generated OpenAPI spec.Why would it be useful?
We use the OpenAPI spec to dynamically generate forms to interact with the APIs. Sometimes, we want to add additional metadata that's not strictly necessary for the API itself, but is useful to other tooling. An example of this might be the grouping of multiple properties into a fieldset, e.g. something like:
In this case, a downstream tool might look at the
fieldsets
extension and deduce that the fieldsname
,age
, andshoesize
should belong to a fieldset calledPersonal information
, and the fieldaddress
should belong to another fieldset calledContact information
. What a fieldset is, or how to interpret this schema, is entirely up to that tool and has nothing to do with Fern.Describe the solution (optional)
The OpenAPI spec allows for schema objects to use specification extensions. I propose that the
extensions
object should (by default) generate corresponding specification extensions in the generated OpenAPI spec. In the aforementioned example, the generated OpenAPI spec might have something like the following in its schema:So essentially, the data for each property is simply passed along verbatim, with the only transformation being to the property name such that it adheres to the
x-{name}
format required by the OpenAPI specification.Additional context
The text was updated successfully, but these errors were encountered: