[Feature] Display minimum and maximum values in API reference

[hkosova]

Problem description

As an API vendor / technical writer who uses OpenAPI,
I want to display allowed value ranges in the API reference
to help my users construct successful requests and avoid validation errors.

OpenAPI Specification has keywords to define min/max limits for values:

• minimum, maximum, exclusiveMinimum, and exclusiveMaximum for numbers (both integers and floating-point)
  • Note: exclusiveM* have different value type and behavior in OpenAPI 3.1+ vs OpenAPI <= 3.0
• minLength and maxLength for strings
• minItems and maxItems for arrays
• minProperties and maxProperties for objects

Fern's API reference currently does not show these attributes. Whereas most other OpenAPI renderers show them so it's a noticeable gap in Fern's OpenAPI coverage.

Why would it be useful?

Allowed value ranges are essential information in any reference documentation (along with data types, enum values, etc.), so that client developers know which values are valid and which are not.

Describe the solution

• API reference displays minimum and maximum values for parameters, request fields, and response fields.
• API playground displays minimum and maximum values in the tooltips of parameters and request fields.

Special cases where min/max attributes may need to be displayed a bit differently:

• string minLength = maxLength, e.g. a string 5 characters long
• array minItems = maxItems, e.g. an array that always contains 2 items
• object minProperties = maxProperties, e.g. an object that always contains 2 properties

Additional context

Here're some examples of how other OpenAPI renderers show display min/max values. I personally like Redoc and Swagger UI versions.

Bump.sh

https://bump.sh/preview?url=https%3A%2F%2Fgist.githubusercontent.com%2Fhkosova%2Fdc9ea2c285b61cd36a5ec8eb18b43676%2Fraw%2F7defc7378734e7494d7ec3a2bf0928bc7fe9ff48%2Fmin-max.yaml&commit=Preview

ReadMe

https://preview.readme.io/reference/get_something?url=https%3A%2F%2Fgist.githubusercontent.com%2Fhkosova%2Fb23af6d24f55023f9771bc805b762a18%2Fraw%2Fa5ba6ee45d7f57f4b54c3cb636315bd9ba6cdc97%2Fmin-max.json

Redoc

https://redocly.github.io/redoc/?nocors&url=https://gist.githubusercontent.com/hkosova/dc9ea2c285b61cd36a5ec8eb18b43676/raw/7defc7378734e7494d7ec3a2bf0928bc7fe9ff48/min-max.yaml#tag/Webhooks/paths/moniteWebhook/post

Stoplight Elements

https://elements-demo.stoplight.io/?spec=https://gist.githubusercontent.com/hkosova/dc9ea2c285b61cd36a5ec8eb18b43676/raw/7defc7378734e7494d7ec3a2bf0928bc7fe9ff48/min-max.yaml

Swagger UI

https://petstore.swagger.io/?showCommonExtensions=true&url=https://gist.githubusercontent.com/hkosova/dc9ea2c285b61cd36a5ec8eb18b43676/raw/7defc7378734e7494d7ec3a2bf0928bc7fe9ff48/min-max.yaml#/

---

Sample OpenAPI spec for testing (note: does not include min/maxProperties and exclusiveMinimum/Maximum).

https://gist.githubusercontent.com/hkosova/dc9ea2c285b61cd36a5ec8eb18b43676/raw/7defc7378734e7494d7ec3a2bf0928bc7fe9ff48/min-max.yaml

openapi: 3.1.0
info:
  title: Min/max constraints
  version: 1.0.0
paths:
  /something:
    get:
      summary: Something something
      parameters:
        - in: query
          name: num_min
          schema:
            type: integer
            minimum: 1
        - in: query
          name: num_max
          schema:
            type: integer
            maximum: 100
        - in: query
          name: num_min_max
          schema:
            type: integer
            minimum: -1
            maximum: 100
        - in: query
          name: str_min
          schema:
            type: string
            minLength: 1
        - in: query
          name: str_max
          schema:
            type: string
            maxLength: 10
        - in: query
          name: str_min_max
          schema:
            type: string
            minLength: 1
            maxLength: 10
        - in: query
          name: str_fixed_length
          schema:
            type: string
            minLength: 4
            maxLength: 4
        - in: query
          name: arr_min
          schema:
            type: array
            items:
              type: string
            minItems: 1
        - in: query
          name: arr_max
          schema:
            type: array
            items:
              type: string
            maxItems: 5
        - in: query
          name: arr_min_max
          schema:
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 5
        - in: query
          name: arr_fixed_items
          schema:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Something'

components:
  schemas:
    Something:
      type: object
      properties:
        num_min:
          type: integer
          minimum: 1
        num_max:
          type: integer
          maximum: 100
        num_min_max:
          type: integer
          minimum: -1
          maximum: 100
        str_min:
          type: string
          minLength: 1
        str_max:
          type: string
          maxLength: 10
        str_min_max:
          type: string
          minLength: 1
          maxLength: 10
        str_fixed_length:
          type: string
          minLength: 4
          maxLength: 4
        arr_min:
          type: array
          items:
            type: string
          minItems: 1
        arr_max:
          type: array
          items:
            type: string
          maxItems: 5
        arr_min_max:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 5
        arr_fixed_items:
          type: array
          items:
            type: string
          minItems: 2
          maxItems: 2