As an API consumer, I want precise information about data types and formats used by the API.
Problem description
OpenAPI has the format keyword to narrow down the type of values. Some commonly used formats are defined by the OpenAPI Format Registry and JSON Schema, but in general format is an open-ended annotation that can be an arbitrary string, e.g. format: a comma-separated string.
Our API has a lot of string parameters and schema fields with format: uuid, format: date, and format: email, and we would like to have all of these formats (and possible others) indicated in the API Reference.
Currently Fern displays only format: date-time but not the other formats, from what I can see.
Why would it be useful?
Additional helpful information for API consumers.
No perceived information loss for API vendors who migrate to Fern from other documentation tools.
Describe the solution
API reference (and probably API playground too) displays the format of parameters, schemas, and schema fields.
Not just the common formats, but any literal format value as it is defined in the OpenAPI document.
Format should be displayed next to (or instead of) the data type, e.g. as string (uuid) or just uuid (without "string") or in a similar way.
As an API consumer, I want precise information about data types and formats used by the API.
Problem description
OpenAPI has the
format
keyword to narrow down thetype
of values. Some commonly used formats are defined by the OpenAPI Format Registry and JSON Schema, but in generalformat
is an open-ended annotation that can be an arbitrary string, e.g.format: a comma-separated string
.Our API has a lot of string parameters and schema fields with
format: uuid
,format: date
, andformat: email
, and we would like to have all of these formats (and possible others) indicated in the API Reference.Currently Fern displays only
format: date-time
but not the other formats, from what I can see.Why would it be useful?
Describe the solution
format
of parameters, schemas, and schema fields.format
s, but any literalformat
value as it is defined in the OpenAPI document.type
, e.g. asstring (uuid)
or justuuid
(without "string") or in a similar way.Additional context
How other OpenAPI renderers display formats:
Bump.sh: https://bump.sh/preview?url=https://gist.githubusercontent.com/hkosova/34bfb106931ff9535068db184c3b65ec/raw/a50bc00d4ecd180548525d2bb5e3b30374f0edbc/formats.yaml&commit=Preview
Redoc: https://redocly.github.io/redoc/?nocors&url=https://gist.githubusercontent.com/hkosova/34bfb106931ff9535068db184c3b65ec/raw/a50bc00d4ecd180548525d2bb5e3b30374f0edbc/formats.yaml#/paths/~1foos/get
Stoplight Elements: https://elements-demo.stoplight.io/?spec=https://gist.githubusercontent.com/hkosova/34bfb106931ff9535068db184c3b65ec/raw/a50bc00d4ecd180548525d2bb5e3b30374f0edbc/formats.yaml#/paths/foos/get
Swagger UI: https://petstore3.swagger.io/?url=https://gist.githubusercontent.com/hkosova/34bfb106931ff9535068db184c3b65ec/raw/a50bc00d4ecd180548525d2bb5e3b30374f0edbc/formats.yaml#/default/get_foos
Sample OpenAPI document for testing: