Propagate GraphQL field descriptions to auto-generated FilterParameter / SortParameter

[tianyingchun]

When a custom GraphQL object type defines field descriptions (via SDL """...""" or equivalent), Vendure’s generateListOptions() builds {Type}FilterParameter and {Type}SortParameter without copying those descriptions.

As a result, GraphiQL / GraphQL introspection shows helpful docs on the output type (e.g. QuantsStockBasic.tsCode), but the matching filter/sort input fields (e.g. QuantsStockBasicFilterParameter.tsCode) have empty descriptions, even though they represent the same business fields.

This is less a runtime bug and more a DX / schema documentation gap in list-options generation.

To Reproduce

Steps to reproduce the behavior:

Extend Shop (or Admin) API with a custom type that has field descriptions, e.g.:

type ProductNote implements Node {
  id: ID!
  """SKU or product code used for lookup"""
  code: String!
  """Human-readable note body"""
  body: String
}

type ProductNoteList implements PaginatedList {
  items: [ProductNote!]!
  totalItems: Int!
}

input ProductNoteListOptions

extend type Query {
  productNotes(options: ProductNoteListOptions): ProductNoteList!
}

2. Start Vendure so generateListOptions creates ProductNoteFilterParameter / ProductNoteSortParameter.
3. Open GraphiQL (or run introspection) and inspect ProductNote.code → description is present.
4. Inspect ProductNoteFilterParameter.code (and ProductNoteSortParameter.code) → description is missing.

Expected behavior

Auto-generated list filter/sort input fields should inherit the description from the corresponding field on the source object type (when present), so API docs, GraphiQL, MCP/OpenAPI generators, and codegen all stay consistent.

Actual behavior

createFilterParameter / createSortParameter in @vendure/core only set type on each generated input field and omit description, so introspection returns null for those fields even when the source object field has a description.

Relevant code (v3.7.1): dist/api/config/generate-list-options.js — createSortParameter / createFilterParameter field config currently looks like:

const fieldConfig = {
  type: SortOrder, // or filterType
  // description is not set
};

Screenshots/Videos

GraphiQL Docs for *FilterParameter shows field names + operator types only; no description text under fields that are documented on the parent object type.

Error logs

N/A — schema builds successfully; only documentation metadata is missing.

Environment (please complete the following information):

@vendure/core version: 3.7.1
Nodejs version: v24.14.1
Database (mysql/postgres etc): MySQL (not relevant)
Operating System (Windows/macOS/Linux): macOS
Browser (if applicable): GraphiQL in browser
Package manager (npm/yarn/pnpm): Yarn 4.17.1
Configuration

Not configuration-specific. Any plugin/schema that:

Defines an object type with field descriptions, and
Declares input XxxListOptions for Vendure to expand
will reproduce this.

Minimal reproduction

See “To Reproduce” SDL above. After boot, introspection:

{
  __type(name: "ProductNote") {
    fields { name description }
  }
  __type(name: "ProductNoteFilterParameter") {
    inputFields { name description }
  }
}

Expect: ProductNote.code.description is non-null; ProductNoteFilterParameter.code.description is null today.

Workaround

Local patch of @vendure/core generate-list-options to pass through descriptions:

 const fieldConfig = {
   type: SortOrder, // or filterType
+  description: field.description ?? undefined,
 };

Applied in both createSortParameter and createFilterParameter.

Additional context

Consistent / always reproducible on current Vendure list-options generation.
Especially painful for data APIs where filter inputs are the main surface developers explore in GraphiQL.
ListOptions wrapper fields (skip / take / filter / sort / filterOperator) already have descriptions; only per-entity filter/sort fields lose the source field docs.
Happy to open a PR with the two-line change if this is accepted as intended behavior.
Proposed change

In createSortParameter and createFilterParameter, when building each fieldConfig, set:

description: field.description ?? undefined

so generated *FilterParameter / *SortParameter fields mirror the documented meaning of the entity fields.

[tianyingchun]

it works fine.