As an API consumer, I want to see realistic example values in the API reference.
As an API vendor / technical writer,
I want the API documentation tool to automatically generated request and response example values for our API schemas,
so that we don't have to manually add example values to the OpenAPI spec.
Problem description
Fern already auto-generates custom example values for string fields with format: date-time, but for all other string formats it currently uses the field name as the example value.
It would be great if the tool also generated custom example values for other common string formats - date, email, uuid, etc. (Ideally for all formats from the OpenAPI Format Registry, but realistically maybe just for the top used formats - refer to this 2021 report.)
Why would it be useful?
API vendors don't need to manually include example values in the OpenAPI spec because the documentation tool takes care of generating realistic example values.
Users get a better idea of how the data in requests and responses looks like.
Feature parity with other OpenAPI renderers (Redoc, Swagger UI, etc.)
Describe the solution
For format: date, use the current date OR the same date you use for format: date-time.
For format: email, use an example email address, e.g. ...@example.com or ...@example.org.
For format: hostname, also use the example domain (example.com/.org/.net/...).
As an API consumer, I want to see realistic example values in the API reference.
As an API vendor / technical writer, I want the API documentation tool to automatically generated request and response example values for our API schemas, so that we don't have to manually add example values to the OpenAPI spec.
Problem description
Fern already auto-generates custom example values for string fields with
format: date-time
, but for all other stringformat
s it currently uses the field name as the example value.It would be great if the tool also generated custom example values for other common string formats -
date
,email
,uuid
, etc. (Ideally for all formats from the OpenAPI Format Registry, but realistically maybe just for the top used formats - refer to this 2021 report.)Why would it be useful?
Describe the solution
format: date
, use the current date OR the same date you use forformat: date-time
.format: email
, use an example email address, e.g....@example.com
or...@example.org
.format: hostname
, also use the example domain (example.com/.org/.net/...).format: ipv4
andipv6
, use one of the IP addresses reserved for documentation purposes (see Scope = Documentation).Additional context
How others generate example values:
openapi-sampler
used by Redocjson-schema-sampler
used by StoplightSample OpenAPI spec: