feat: API specs update for version 1.9.x#84
Conversation
Greptile SummaryThis PR updates the 1.9.x API specs and generated examples. The main changes are:
Confidence Score: 3/5Several schema/example mismatches can affect generated clients, docs, and validation workflows, so the spec updates need targeted fixes before merging. The review covered the changed OpenAPI specs and generated examples, with focused runtime checks confirming the main type-shape issues in the spec data. specs/1.9.x/open-api3-1.9.x-client.json, specs/1.9.x/open-api3-1.9.x-server.json, examples/1.9.x/server-nodejs/examples/usage/list-events.md, examples/1.9.x/server-graphql/examples/usage/list-events.md
 T-Rex LogsWhat T-Rex did
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| "name": "resource", | ||
| "description": "RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.", | ||
| "required": false, | ||
| "schema": { | ||
| "type": "string", | ||
| "default": [] | ||
| }, | ||
| "in": "query" | ||
| } |
There was a problem hiding this comment.
The new OAuth2 resource parameter is declared as a string, but its default is an array. Strict OpenAPI consumers and SDK generators can treat this optional string as the wrong type, producing invalid generated defaults or request builders for authorize/device/token flows. The same resource schema should use a string default, such as "", or be modeled as an array if multiple values are intended.
Artifacts
Repro: validation harness for OAuth2 resource default type mismatch
- Contains supporting evidence from the run (text/javascript; charset=utf-8).
Stack trace captured during the T-Rex run
- Keeps the raw stack trace available without making the summary code-heavy.
| "metrics": { | ||
| "type": "array", | ||
| "description": "Aggregated groups ordered by time ascending.", | ||
| "description": "One entry per requested metric, each carrying its own points[] time series (sums per bucket \/ dimension over time).", | ||
| "items": { | ||
| "$ref": "#\/components\/schemas\/usageGroup" | ||
| "$ref": "#\/components\/schemas\/usageMetric" | ||
| }, | ||
| "x-example": "" | ||
| } | ||
| }, | ||
| "required": [ | ||
| "metric", | ||
| "interval", | ||
| "groups" | ||
| "metrics" | ||
| ], | ||
| "example": { | ||
| "metric": "executions", | ||
| "interval": "1d", | ||
| "groups": "" | ||
| "metrics": "" |
There was a problem hiding this comment.
usageEventList.metrics is an array of usageMetric, but the schema example and x-example set it to an empty string. Generated docs and validators that check examples against schemas will see an invalid response shape, and SDK example generation can show metrics as a string instead of a list of metric series.
Artifacts
Repro: focused usageEventList metrics example validation script
- Contains supporting evidence from the run (text/x-python; charset=utf-8).
Repro: validator output showing metrics array schema and string example mismatches
- Keeps the command output available without making the summary code-heavy.
| "metrics": { | ||
| "type": "array", | ||
| "description": "Aggregated groups ordered by time ascending. Each group carries the latest snapshot in its interval (argMax over time).", | ||
| "description": "One entry per requested metric, each carrying its own points[] time series (latest-snapshot per bucket \/ dimension via argMax over time).", | ||
| "items": { | ||
| "$ref": "#\/components\/schemas\/usageGroup" | ||
| "$ref": "#\/components\/schemas\/usageMetric" | ||
| }, | ||
| "x-example": "" | ||
| } | ||
| }, | ||
| "required": [ | ||
| "metric", | ||
| "interval", | ||
| "groups" | ||
| "metrics" | ||
| ], | ||
| "example": { | ||
| "metric": "files.storage", | ||
| "interval": "1d", | ||
| "groups": "" | ||
| "metrics": "" |
There was a problem hiding this comment.
usageGaugeList.metrics is also declared as an array of usageMetric, but its example value is "". Any generated response examples or schema validation based on this spec can produce an invalid gauge response where callers see a string instead of the required metrics array.
Artifacts
Repro: focused usageGaugeList metrics example validator
- Contains supporting evidence from the run (text/x-python; charset=utf-8).
Repro: validation output showing array schema and string examples
- Keeps the command output available without making the summary code-heavy.
|
|
||
| const result = await usage.listEvents({ | ||
| metric: '<METRIC>', | ||
| metrics: [], |
There was a problem hiding this comment.
The new API marks metrics[] as required with one to ten metric names, but this example passes an empty array. Copying it will send a request with no requested metrics, which can fail validation or return no useful data. The examples should use a one-element array, matching the spec text.
| metrics: [], | |
| metrics: ['executions'], |
| query { | ||
| usageListEvents( | ||
| metric: "<METRIC>", | ||
| metrics: [], |
There was a problem hiding this comment.
The usage endpoint requires one to ten metric names, but the GraphQL example passes metrics: []. A copied query asks for no series, so it can fail validation or return an empty result instead of demonstrating the new response shape.
| metrics: [], | |
| metrics: ["executions"], |
1 participant
This PR contains API specification updates for version 1.9.x.