Display minimum and maximum values in API reference #5141
Description
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, andexclusiveMaximumfor numbers (both integers and floating-point)- Note:
exclusiveM*have different value type and behavior in OpenAPI 3.1+ vs OpenAPI <= 3.0
- Note:
minLengthandmaxLengthfor stringsminItemsandmaxItemsfor arraysminPropertiesandmaxPropertiesfor 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
ReadMe
Redoc
Stoplight Elements
Swagger UI
Sample OpenAPI spec for testing (note: does not include min/maxProperties and exclusiveMinimum/Maximum).
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