upstream/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2026-05-28 04:02:21 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Address PR feedback: fix typo, move examples, clarify supported duration format

Browse source 
Signed-off-by: Charles Korn <charles.korn@grafana.com>
This commit is contained in:
Charles Korn 2026-03-17 10:40:56 +11:00
parent c588fd2338
commit 8763eef666
No known key found for this signature in database
4 changed files with 72 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
web/api/v1/openapi_helpers.go
View file

@ -174,15 +174,15 @@ func durationSchema() *base.SchemaProxy {
base.CreateSchemaProxy(&base.Schema{
Type: []string{"string"},
Format: "duration",
Description: "Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.",
Description: "Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).",
}),
base.CreateSchemaProxy(&base.Schema{
Type: []string{"number"},
Format: "float",
Description: "Fractional number of seconds, such as 2 or 4.5.",
Description: "Fractional number of seconds.",
}),
},
Description: "Duration in humand-readable or numeric format.",
Description: "Duration in human-readable or numeric format.",
})
}

10
web/api/v1/openapi_paths.go
View file

@ -30,8 +30,8 @@ func (*OpenAPIBuilder) queryPath() *v3.PathItem {
queryParamWithExample("limit", "The maximum number of metrics to return.", false, integerSchema(), []example{{"example", 100}}),
queryParamWithExample("time", "The evaluation timestamp (optional, defaults to current time).", false, timestampSchema(), timestampExamples(exampleTime)),
queryParamWithExample("query", "The PromQL query to execute.", true, stringSchema(), []example{{"example", "up"}}),
queryParamWithExample("timeout", "Evaluation timeout. Optional. Defaults to and is capped by the value of the -query.timeout flag.", false, durationSchema(), []example{{"example", "30s"}}),
queryParamWithExample("lookback_delta", "Override the lookback period for this query. Optional.", false, durationSchema(), []example{{"example", "5m"}}),
queryParamWithExample("timeout", "Evaluation timeout. Optional. Defaults to and is capped by the value of the -query.timeout flag.", false, durationSchema(), []example{{"duration", "1m30s"}, {"number", "90"}}),
queryParamWithExample("lookback_delta", "Override the lookback period for this query. Optional.", false, durationSchema(), []example{{"duration", "5m"}, {"number", "300"}}),
queryParamWithExample("stats", "When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.", false, stringSchema(), []example{{"example", "all"}}),
}
return &v3.PathItem{
@ -57,10 +57,10 @@ func (*OpenAPIBuilder) queryRangePath() *v3.PathItem {
queryParamWithExample("limit", "The maximum number of metrics to return.", false, integerSchema(), []example{{"example", 100}}),
queryParamWithExample("start", "The start time of the query.", true, timestampSchema(), timestampExamples(exampleTime.Add(-1*time.Hour))),
queryParamWithExample("end", "The end time of the query.", true, timestampSchema(), timestampExamples(exampleTime)),
queryParamWithExample("step", "The step size of the query.", true, durationSchema(), []example{{"example", "15s"}}),
queryParamWithExample("step", "The step size of the query.", true, durationSchema(), []example{{"duration", "15s"}, {"number", "15"}}),
queryParamWithExample("query", "The query to execute.", true, stringSchema(), []example{{"example", "rate(prometheus_http_requests_total{handler=\"/api/v1/query\"}[5m])"}}),
queryParamWithExample("timeout", "Evaluation timeout. Optional. Defaults to and is capped by the value of the -query.timeout flag.", false, durationSchema(), []example{{"example", "30s"}}),
queryParamWithExample("lookback_delta", "Override the lookback period for this query. Optional.", false, durationSchema(), []example{{"example", "5m"}}),
queryParamWithExample("timeout", "Evaluation timeout. Optional. Defaults to and is capped by the value of the -query.timeout flag.", false, durationSchema(), []example{{"duration", "1m30s"}, {"number", "90"}}),
queryParamWithExample("lookback_delta", "Override the lookback period for this query. Optional.", false, durationSchema(), []example{{"duration", "5m"}, {"number", "300"}}),
queryParamWithExample("stats", "When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.", false, stringSchema(), []example{{"example", "all"}}),
}
return &v3.PathItem{

54
web/api/v1/testdata/openapi_3.1_golden.yaml vendored
View file

@ -65,14 +65,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
value: 30s
duration:
value: 1m30s
number:
value: "90"
- name: lookback_delta
in: query
description: Override the lookback period for this query. Optional.
@ -82,14 +84,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
duration:
value: 5m
number:
value: "300"
- name: stats
in: query
description: When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.
@ -265,14 +269,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
duration:
value: 15s
number:
value: "15"
- name: query
in: query
description: The query to execute.
@ -292,14 +298,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
value: 30s
duration:
value: 1m30s
number:
value: "90"
- name: lookback_delta
in: query
description: Override the lookback period for this query. Optional.
@ -309,14 +317,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
duration:
value: 5m
number:
value: "300"
- name: stats
in: query
description: When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.

54
web/api/v1/testdata/openapi_3.2_golden.yaml vendored
View file

@ -65,14 +65,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
value: 30s
duration:
value: 1m30s
number:
value: "90"
- name: lookback_delta
in: query
description: Override the lookback period for this query. Optional.
@ -82,14 +84,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
duration:
value: 5m
number:
value: "300"
- name: stats
in: query
description: When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.
@ -265,14 +269,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
duration:
value: 15s
number:
value: "15"
- name: query
in: query
description: The query to execute.
@ -292,14 +298,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
value: 30s
duration:
value: 1m30s
number:
value: "90"
- name: lookback_delta
in: query
description: Override the lookback period for this query. Optional.
@ -309,14 +317,16 @@ paths:
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
example:
duration:
value: 5m
number:
value: "300"
- name: stats
in: query
description: When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.