AuthoredParamDocs

Kind: Type

Source: atloria-monorepo/libs/parser-core/src/openapi/doc-annotations.ts

The developer's own words, recovered from source and carried to the published spec.

Before this module every operation was published as summary = <methodName> — getMe, listAssets, record — even when the file directly above the handler said @ApiOperation({ summary: 'Get the OpenAPI spec for the API playground' }). The prose was parsed away and a camelCase identifier substituted for it. 536 of our own 634 operations read that way, and not one carried a description.

Every framework has its own place to write this down — a decorator argument, an attribute, a docblock, a docstring, a magic comment — but they all answer the same three questions, so the extraction differs per language while the RESULT is one shape (AuthoredDocs) that the endpoint pipeline understands.

Two rules run through everything here:

1. Precedence, never overwrite downward. An explicit annotation (@ApiOperation, @Operation, summary=) is the contract the author published on purpose, so it beats a doc comment, which in turn beats the derived method name. mergeAuthoredDocs is the only place that ordering lives, so no parser can get it backwards.

2. Never invent prose. Every field here is optional and stays undefined when the source said nothing. A caller that gets {} must keep its existing behaviour exactly. A summary we made up is worse than a method name, because a method name is at least honestly derived and a reader can see that it is.

Definition

ts
Record<string, string>