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] Display formats of data types #5160

Open hkosova opened 5 days ago

hkosova commented 5 days ago

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?

Describe the solution

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:

openapi: 3.1.0
info:
  title: Data formats
  version: 1.0.0
paths:
  /foos:
    get:
      summary: Search foos
      parameters:
        - in: query
          name: id__in
          schema:
            type: array
            items:
              type: string
              format: uuid
        - in: query
          name: due_date
          schema:
            type: string
            format: date
        - in: query
          name: customer_email
          schema:
            type: string
            format: email
        - in: query
          name: created_at__gte
          schema:
            type: string
            format: date-time
      responses:
        '201':
          description: A list of food
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Foo'

components:
  schemas:
    Foo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        due_date:
          type: string
          format: date
        customer_email:
          type: string
          format: email

        arbitrary_format_1:
          type: string
          format: ISO 8601 duration
        arbitrary_format_2:
          type: string
          format: Unix timestamp
        arbitrary_format_3:
          type: string
          format: comma-separated
paolofulgoni commented 2 days ago

We have the same issue with the date format. We add example values as a workaround.