RobinTail / express-zod-api / 31018938863

100%

push

github

fix(Documentation): Force path params to be required (#3602)

## What

Fixes #3600. Path parameters declared optional in the input schema were
being documented with `required: false`, which is both non-compliant
with the OpenAPI Parameter Object (which mandates `required: true` for
`in: "path"`) and misleading, since Express only routes a request when
the path segment is present.

### Change 1 — Document path params as required

In `depictRequestParams` (`src/documentation-helpers.ts`), the emitted
`required` flag now forces `true` for path-located parameters via a
small `isParamRequired` helper. Query/header/cookie parameters keep
their existing behavior.

### Change 2 — Startup diagnostic

`Diagnostics.#checkParams` (`src/diagnostics.ts`) now warns when a path
parameter is present in the input schema but declared optional. The
logic lives in a new private `#checkOptionalPathParams` helper (to keep
`#checkParams` under the ESLint `complexity` gate), built on a snapshot
of the path-param set taken before the property loop so it stays
distinct from the existing missing-parameter warning.

```
The path parameter "X" is declared optional in the input schema, but path parameters are always required since Express matches the route only when the segment is present.
```

## Tests

- `tests/documentation-helpers.spec.ts` — path param with optional
schema emits `required: true`; query param stays `required: false`.
- `tests/documentation.spec.ts` — an optional path param endpoint emits
a param with `in: "path"` and `required: true`.
- `tests/routing.spec.ts` — optional path param logs the warning; a
required path param does not.

## Validation

- `pnpm exec eslint` on changed files: clean.
- `tsc --noEmit`: clean.
- `vitest run` on the three affected spec files: 197 tests pass.

<!-- PULLFROG_DIVIDER_DO_NOT_REMOVE_PLZ -->
<sup><a href="https://pullfrog.com"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://pullfrog.com/logos/frog-white-full... (continued)

1056 of 1107 branches covered (95.39%)

3 of 3 new or added lines in 1 file covered. (100.0%)

1514 of 1514 relevant lines covered (100.0%)

559.75 hits per line