docs(api): fill generated query descriptions#4624
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Greptile SummaryThis PR fills the 74 empty OpenAPI query-parameter descriptions identified in #4606 by adding leading proto comments to every previously-undocumented
Confidence Score: 4/5Safe to merge; changes are limited to proto documentation comments and their regenerated OpenAPI artifacts with no runtime code paths touched. The proto comments and regenerated OpenAPI files are accurate and mechanically consistent. The new CI guard closes the documentation gap cleanly. Two minor issues: a redundant trailing inline comment on
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[proto/*.proto\nAdd leading comments to\nquery fields] --> B[make generate\nbuf + sebuf plugins]
B --> C[docs/api/*.openapi.json\nPer-service JSON specs\n341 query params described]
B --> D[docs/api/*.openapi.yaml\nPer-service YAML specs]
B --> E[docs/api/worldmonitor.openapi.yaml\nUnified spec]
C --> F[generated-api-description-guard.test.mjs\ncollectQueryParameters guard\nFails CI if any query param\nlacks a description]
C --> G[LEGACY_HIGH_RISK_DESCRIPTION_GAPS\nRemove 5 stale entries\nnow covered by new comments]
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A[proto/*.proto\nAdd leading comments to\nquery fields] --> B[make generate\nbuf + sebuf plugins]
B --> C[docs/api/*.openapi.json\nPer-service JSON specs\n341 query params described]
B --> D[docs/api/*.openapi.yaml\nPer-service YAML specs]
B --> E[docs/api/worldmonitor.openapi.yaml\nUnified spec]
C --> F[generated-api-description-guard.test.mjs\ncollectQueryParameters guard\nFails CI if any query param\nlacks a description]
C --> G[LEGACY_HIGH_RISK_DESCRIPTION_GAPS\nRemove 5 stale entries\nnow covered by new comments]
Reviews (1): Last reviewed commit: "docs(api): fill generated query descript..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| // Fuel mode to model: "oil", "gas", or "both". Defaults to "oil". | ||
| string fuel_mode = 4 [(sebuf.http.query) = {name: "fuel_mode"}]; // "oil"|"gas"|"both", default "oil" |
There was a problem hiding this comment.
fuel_mode is now redundant — the leading proto comment added in this PR already documents the valid values and default. The duplicate inline comment will not be surfaced in generated OpenAPI (only leading comments are picked up by buf generate) and adds maintenance noise if the accepted values ever change.
| // Fuel mode to model: "oil", "gas", or "both". Defaults to "oil". | |
| string fuel_mode = 4 [(sebuf.http.query) = {name: "fuel_mode"}]; // "oil"|"gas"|"both", default "oil" | |
| // Fuel mode to model: "oil", "gas", or "both". Defaults to "oil". | |
| string fuel_mode = 4 [(sebuf.http.query) = {name: "fuel_mode"}]; |
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| it('requires every generated query parameter to have a description', () => { | ||
| const missingDescriptions = collectQueryParameters() | ||
| .filter((row) => !row.description) | ||
| .map((row) => row.key) | ||
| .sort(); | ||
|
|
||
| assert.deepEqual( | ||
| missingDescriptions, | ||
| [], | ||
| 'Generated OpenAPI query parameters are missing descriptions:\n' + missingDescriptions.join('\n'), | ||
| ); | ||
| }); |
There was a problem hiding this comment.
rejects placeholder descriptions test for high-risk schema properties, it does not apply MISLEADING_DESCRIPTION_PATTERNS (which catches "TODO", "TBD", bare type names, etc.). A query field with // TODO: fill later in proto would pass this guard. Applying the same placeholder check keeps the two guards consistent.
| it('requires every generated query parameter to have a description', () => { | |
| const missingDescriptions = collectQueryParameters() | |
| .filter((row) => !row.description) | |
| .map((row) => row.key) | |
| .sort(); | |
| assert.deepEqual( | |
| missingDescriptions, | |
| [], | |
| 'Generated OpenAPI query parameters are missing descriptions:\n' + missingDescriptions.join('\n'), | |
| ); | |
| }); | |
| it('requires every generated query parameter to have a description', () => { | |
| const missingDescriptions = collectQueryParameters() | |
| .filter((row) => !row.description) | |
| .map((row) => row.key) | |
| .sort(); | |
| assert.deepEqual( | |
| missingDescriptions, | |
| [], | |
| 'Generated OpenAPI query parameters are missing descriptions:\n' + missingDescriptions.join('\n'), | |
| ); | |
| const placeholders = collectQueryParameters() | |
| .filter((row) => row.description && MISLEADING_DESCRIPTION_PATTERNS.some((pattern) => pattern.test(row.description))) | |
| .map((row) => `${row.key}: ${row.description}`) | |
| .sort(); | |
| assert.deepEqual( | |
| placeholders, | |
| [], | |
| 'Generated OpenAPI query parameters have placeholder descriptions:\n' + placeholders.join('\n'), | |
| ); | |
| }); |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
- mark ignored calendar and natural-event query params as accepted-but-ignored no-ops - cover bundled worldmonitor.openapi.yaml in the generated query-description guard
1 participant
Summary
(sebuf.http.query)request field from docs(api): fill 74 empty OpenAPI param descriptions (proto field-comment convention + buf-lint) (#4599) #4606.tests/generated-api-description-guard.test.mjsto fail CI when any generated query parameter has an empty or placeholder description, and retired stale allowlist entries fixed by this change.Intent
Fix the 74 empty generated OpenAPI query parameter descriptions identified in #4606 through the upstream proto-comment convention.
Non-goals: response-schema description debt still listed in the existing high-risk allowlist, runtime endpoint behavior, auth/rate-limit behavior, and broader proto lint cleanup.
Validation Matrix
TOTAL_EMPTY=74, matching the issue scopenpm ci --ignore-scripts --cache /tmp/worldmonitor-npm-cache --prefer-offlineNO_COMMENT_QUERY_FIELDS=0PATH="$PWD/node_modules/.bin:$PATH" GOTOOLCHAIN=auto make generatenode --test tests/generated-api-description-guard.test.mjsTOTAL_QUERY=341,TOTAL_EMPTY=0,TOTAL_PLACEHOLDER=0npm run lint:api-contractnode --test tests/market-methodology-doc-contracts.test.mjsnpm run typecheck:apinpm run typechecktsc --noEmitpassgit diff --checkPATH="$PWD/node_modules/.bin:$PATH" make lintReview Gates
983102a6(removed redundant inlinefuel_modecomment; added placeholder rejection for query params). Final checks pass.Documentation
Generated API documentation updated in
docs/api/*.openapi.{json,yaml}anddocs/api/worldmonitor.openapi.yaml. No prose docs required.Screenshots / UI Evidence
Not applicable. This is generated API documentation/proto metadata only; no UI changed.
Residual Findings
make lintremains blocked by existing unrelated repo-wide proto lint debt outside this issue. The focused source scan and generated OpenAPI guard cover this PR's acceptance criteria.983102a6; I did not resolve or reply to review threads per loop rules.