mirrors/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2026-05-17 18:46:48 +02:00
Code Issues Projects Releases Wiki Activity

chore: document supported formats for duration query request parameters in OpenAPI spec

Browse Source 
Signed-off-by: Charles Korn <charles.korn@grafana.com>
This commit is contained in:
Charles Korn 2026-03-16 16:47:37 +11:00
parent 8b25b26a76
commit c588fd2338
No known key found for this signature in database
4 changed files with 103 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
web/api/v1/openapi_helpers.go
View File

@ -168,6 +168,24 @@ func timestampSchema() *base.SchemaProxy {
})
}
func durationSchema() *base.SchemaProxy {
return base.CreateSchemaProxy(&base.Schema{
OneOf: []*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.",
}),
base.CreateSchemaProxy(&base.Schema{
Type: []string{"number"},
Format: "float",
Description: "Fractional number of seconds, such as 2 or 4.5.",
}),
},
Description: "Duration in humand-readable or numeric format.",
})
}
func stringSchemaWithConstValue(value string) *base.SchemaProxy {
node := &yaml.Node{Kind: yaml.ScalarNode, Value: value}
return base.CreateSchemaProxy(&base.Schema{

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, stringSchema(), []example{{"example", "30s"}}),
queryParamWithExample("lookback_delta", "Override the lookback period for this query. Optional.", false, stringSchema(), []example{{"example", "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("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, stringSchema(), []example{{"example", "15s"}}),
queryParamWithExample("step", "The step size of the query.", true, durationSchema(), []example{{"example", "15s"}}),
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, stringSchema(), []example{{"example", "30s"}}),
queryParamWithExample("lookback_delta", "Override the lookback period for this query. Optional.", false, stringSchema(), []example{{"example", "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("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{

45
web/api/v1/testdata/openapi_3.1_golden.yaml vendored
View File

@ -62,7 +62,14 @@ paths:
required: false
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 30s
@ -72,7 +79,14 @@ paths:
required: false
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 5m
@ -248,7 +262,14 @@ paths:
required: true
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 15s
@ -268,7 +289,14 @@ paths:
required: false
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 30s
@ -278,7 +306,14 @@ paths:
required: false
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 5m

45
web/api/v1/testdata/openapi_3.2_golden.yaml vendored
View File

@ -62,7 +62,14 @@ paths:
required: false
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 30s
@ -72,7 +79,14 @@ paths:
required: false
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 5m
@ -248,7 +262,14 @@ paths:
required: true
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 15s
@ -268,7 +289,14 @@ paths:
required: false
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 30s
@ -278,7 +306,14 @@ paths:
required: false
explode: false
schema:
type: string
oneOf:
- type: string
format: duration
description: Human-readable form accepted by Go's time.Duration.ParseDuration(), such as 15s or 2m30s.
- type: number
format: float
description: Fractional number of seconds, such as 2 or 4.5.
description: Duration in humand-readable or numeric format.
examples:
example:
value: 5m