API reference drops a parameter's description when it is declared inside the parameter's schema

[2opremio]

Component

Docs

Priority

P2 - Medium (Would be helpful)

Bug Description

A parameter's description is dropped by the API reference when it is declared inside the parameter's schema. Only a description on the parameter object itself renders. Both placements are valid OpenAPI, and a spec generated from a validation library puts it in the schema (zod's .describe() on a query parameter, for instance), so in a generated spec every parameter renders with no description at all.

Steps to reproduce

1. fern/fern.config.json:

   { "organization": "example", "version": "5.80.2" }

2. fern/generators.yml:

   api:
     specs:
       - openapi: ./openapi/openapi.json

3. fern/openapi/openapi.json, with the same text declared in the two valid places:

   {
     "openapi": "3.0.1",
     "info": { "title": "Example API", "version": "0.1.0" },
     "servers": [{ "url": "https://api.example.com" }],
     "paths": {
       "/widgets": {
         "get": {
           "operationId": "listWidgets",
           "summary": "List widgets",
           "tags": ["widgets"],
           "parameters": [
             {
               "name": "cursor",
               "in": "query",
               "schema": { "type": "string", "description": "Description declared inside the schema." }
             },
             {
               "name": "limit",
               "in": "query",
               "description": "Description declared on the parameter.",
               "schema": { "type": "integer" }
             }
           ],
           "responses": { "200": { "description": "OK" } }
         }
       }
     }
   }

4. fern docs dev, then open the endpoint page.

Expected: both parameters render their description.

Actual: only limit does. cursor renders with no description, and the string never appears in the page. The docs payload the page is built from carries:

cursor   description=None
limit    description='Description declared on the parameter.'

Also observed for path parameters, with the same shape.

One exception, which is what makes this easy to misdiagnose: when the parameter's schema is an inline enum, the schema is hoisted to a named type and the description travels with that type, so enum-valued parameters do render their text. Everything else (string, integer, datetime, arrays) loses it.

Environment

• OS: macOS (darwin 25.5.0)
• Node.js: v22.19.0

Versions

Fern CLI version (from fern.config.json): 5.80.2

Workaround

Restate each description on the parameter itself. For a generated spec that cannot be hand-edited, from overlays.yml:

actions:
  - target: $.paths['/widgets'].get.parameters[?(@.name == 'cursor')]
    update:
      description: Description declared inside the schema.

That is one action per parameter, and it has to be repeated for the same parameter on every operation that takes it.

Are you interested in contributing a fix?

No