fern-api / fern

Input OpenAPI. Output SDKs and Docs.
https://buildwithfern.com
Apache License 2.0
2.68k stars 151 forks source link

[Feature][OpenAPI] Generate example values for common string formats: date, email, uuid, etc. #5169

Open hkosova opened 1 week ago

hkosova commented 1 week ago

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?

Describe the solution

Additional context

How others generate example values:

Sample OpenAPI spec:

openapi: 3.0.0
info:
  title: String formats
  version: 1.0.0

paths:
  /foos:
    get:
      summary: Get a foo
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyObject'

components:
  schemas:
    MyObject:
      type: object
      properties:
        str:
          type: string
        date:
          type: string
          format: date
        datetime:
          type: string
          format: date-time
        uuid:
          type: string
          format: uuid
        email:
          type: string
          format: email
        hostname:
          type: string
          format: hostname
        url:
          type: string
          format: uri
        ip:
          type: string
          format: ipv4
        ipv6:
          type: string
          format: ipv6