Merge pull request #18305 from charleskorn/duration-openapi-docs

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

web/api/v1/openapi_helpers.go

@@ -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 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.",
+			}),
+		},
+		Description: "Duration in human-readable or numeric format.",
+	})
+}
+
 func stringSchemaWithConstValue(value string) *base.SchemaProxy {
 	node := &yaml.Node{Kind: yaml.ScalarNode, Value: value}
 	return base.CreateSchemaProxy(&base.Schema{

web/api/v1/openapi_paths.go

@@ -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{{"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, stringSchema(), []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, 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{{"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{

web/api/v1/testdata/openapi_3.1_golden.yaml

@@ -62,20 +62,38 @@ paths:
                   required: false
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.
                   required: false
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.
@@ -248,10 +266,19 @@ paths:
                   required: true
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.
@@ -268,20 +295,38 @@ paths:
                   required: false
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.
                   required: false
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.

web/api/v1/testdata/openapi_3.2_golden.yaml

@@ -62,20 +62,38 @@ paths:
                   required: false
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.
                   required: false
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.
@@ -248,10 +266,19 @@ paths:
                   required: true
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.
@@ -268,20 +295,38 @@ paths:
                   required: false
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.
                   required: false
                   explode: false
                   schema:
-                    type: string
+                    oneOf:
+                        - type: string
+                          format: duration
+                          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.
+                    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.