Add OpenAPI 3.2 specification generation for Prometheus HTTP API by roidelapluie · Pull Request #17825 · prometheus/prometheus

roidelapluie · 2026-01-09T14:27:57Z

This commit introduces an OpenAPI specification for the Prometheus API. After testing multiple code-generation servers with built-in APIs, this implementation uses an independent spec file outside of the critical path. This spec file is tested with a framework present in this pull request.

The specification helps clients know which parameters they can use and is served at /api/v1/openapi.yaml. The spec file will evolve with the Prometheus API and has the same version number.

Downstream projects can tune the APIs presented in the spec file with configuration options using the IncludePaths setting for path filtering.

In the future, there is room to generate a server from this spec file (e.g. with interfaces), but this is out of scope for this pull request.

Architecture:

Core OpenAPI infrastructure (openapi.go): Dynamic spec building, caching, and thread-safe spec generation
Schema definitions (openapi_schemas.go): Complete type definitions for all API request and response types
Path specifications (openapi_paths.go): Endpoint definitions with parameters, request bodies, and response schemas
Examples (openapi_examples.go): Realistic request/response examples
Helper functions (openapi_helpers.go): Reusable builders for common OpenAPI structures

Testing:

Comprehensive test suite with golden file validation
Test helpers package for API testing infrastructure
OpenAPI compliance validation utilities

The golden file captures the complete specification for snapshot testing. Update with: go test -run TestOpenAPIGolden -update-openapi-spec

REVIEWERS: The most important thing to check would be the OpenAPI golden file (web/api/v1/testdata/openapi_golden.yaml). Test scenarios are important as they test the actual OpenAPI spec validity.

Which issue(s) does the PR fix:

Fixes #2392

Does this PR introduce a user-facing change?

[FEATURE] web: Add OpenAPI 3.2 specification for the HTTP API at /api/v1/openapi.yaml

juliusv · 2026-01-12T10:49:16Z

Hey hey thanks, that's a biggie :) Since I don't know much about OpenAPI yet, I will have to study things a bit. I also read the issue at #2392 and saw that @bwplotka has knowledge and opinions on an OpenAPI spec, so his input here would probably be interesting as well.

krajorama

to be continued

web/api/v1/openapi_schemas.go

web/api/v1/openapi_helpers.go

web/api/v1/openapi_paths.go

web/api/v1/openapi_examples.go

krajorama

to be continued

web/api/v1/openapi_examples.go

web/api/v1/openapi_test.go

web/api/v1/openapi.go

web/api/v1/api_scenarios_test.go

web/api/v1/openapi.go

bwplotka

Amazing work

Did you try generate Go client for this? Curious if we can finally replace client_golang api package 🤔

krajorama

This looks fantastic, I did some spot checks on the main endpoints and also let Claude Opus 4.5 take a look.

I've added one more comment, so if we resolve my two comments and Bartek's question, I think we can approve.

web/api/v1/openapi_examples.go

roidelapluie · 2026-01-28T15:04:53Z

I gene

Amazing work

Did you try generate Go client for this? Curious if we can finally replace client_golang api package 🤔

I generated https://github.com/roidelapluie/promclient

krajorama

LGTM

This commit introduces an OpenAPI specification for the Prometheus API. After testing multiple code-generation servers with built-in APIs, this implementation uses an independent spec file outside of the critical path. This spec file is tested with a framework present in this pull request. The specification helps clients know which parameters they can use and is served at /api/v1/openapi.yaml. The spec file will evolve with the Prometheus API and has the same version number. Downstream projects can tune the APIs presented in the spec file with configuration options using the IncludePaths setting for path filtering. In the future, there is room to generate a server from this spec file (e.g. with interfaces), but this is out of scope for this pull request. Architecture: - Core OpenAPI infrastructure (openapi.go): Dynamic spec building, caching, and thread-safe spec generation - Schema definitions (openapi_schemas.go): Complete type definitions for all API request and response types - Path specifications (openapi_paths.go): Endpoint definitions with parameters, request bodies, and response schemas - Examples (openapi_examples.go): Realistic request/response examples - Helper functions (openapi_helpers.go): Reusable builders for common OpenAPI structures Testing: - Comprehensive test suite with golden file validation - Test helpers package for API testing infrastructure - OpenAPI compliance validation utilities The golden file captures the complete specification for snapshot testing. Update with: go test -run TestOpenAPIGolden -update-openapi-spec REVIEWERS: The most important thing to check would be the OpenAPI golden file (web/api/v1/testdata/openapi_golden.yaml). Test scenarios are important as they test the actual OpenAPI spec validity. Signed-off-by: Julien Pivotto <[email protected]>

Add support for both OpenAPI 3.1 and 3.2 specifications with version selection via openapi_version query parameter. Defaults to 3.1 for broader compatibility Signed-off-by: Julien Pivotto <[email protected]>

- Add timestampExamples helper for consistent time formatting - Add exampleMap helper to simplify example creation - Improve example summaries with query details - Add matrix result example for range vector queries Signed-off-by: Julien Pivotto <[email protected]>

Implement the AtST() method required by chunkenc.Iterator interface for FakeSeriesIterator and FakeHistogramSeriesIterator test helpers. The method returns 0 as these test helpers don't use start timestamps Signed-off-by: Julien Pivotto <[email protected]>

Signed-off-by: Julien Pivotto <[email protected]>

Now that prometheus#17825 is merged. Signed-off-by: Julien Pivotto <[email protected]>

SuperQ · 2026-02-11T12:17:42Z

go.mod

 module github.com/prometheus/prometheus

-go 1.24.0
+go 1.25.0


Can we please be more careful about Go version changes? While it's true today that Go 1.26 is the latest release. At the time of this change we still supported Go 1.24.0.

Hello,

This was an arterfact of the library used, but the code did build and was tested with the previous go version.

We have CI tests for go 1.24 and they did run, so I was thinking this change was fine.

Wait .... #17783 :(

#### Description Updates Prometheus dependencies to `v0.310.0`. The main upstream changes were: - `scrape.NewManager` now requires the new constructor shape with `appendable` and `appendableV2`, and rejects calls where both are `nil` or both are set. - Upstream PR: [prometheus/prometheus#17872](prometheus/prometheus#17872) - `web/api/v1.NewAPI` gained an `AppendableV2` argument and new trailing OpenAPI-related options. - Upstream PRs: [prometheus/prometheus#17825](prometheus/prometheus#17825), [prometheus/prometheus#17975](prometheus/prometheus#17975) In this PR, I'm keeping the appenderv1 in place; the adoption of appenderv2 should be done in as a separate task --------- Signed-off-by: Arthur Silva Sens <[email protected]>

##### [\`v3.10.0\`](https://github.com/prometheus/prometheus/releases/tag/v3.10.0) Prometheus now offers a distroless Docker image variant alongside the default busybox image. The distroless variant provides enhanced security with a minimal base image, uses UID/GID 65532 (nonroot) instead of nobody, and removes the VOLUME declaration. Both variants are available with `-busybox` and `-distroless` tag suffixes (e.g., `prom/prometheus:latest-busybox`, `prom/prometheus:latest-distroless`). The busybox image remains the default with no suffix for backwards compatibility (e.g., `prom/prometheus:latest` points to the busybox variant). For users migrating existing **named** volumes from the busybox image to the distroless variant, the ownership can be adjusted with: ``` docker run --rm -v prometheus-data:/prometheus alpine chown -R 65532:65532 /prometheus ``` Then, the container can be started with the old volume with: ``` docker run -v prometheus-data:/prometheus prom/prometheus:latest-distroless ``` User migrating from bind mounts might need to ajust permissions too, depending on their setup. - \[CHANGE] Alerting: Add `alertmanager` dimension to following metrics: `prometheus_notifications_dropped_total`, `prometheus_notifications_queue_capacity`, `prometheus_notifications_queue_length`. [#16355](prometheus/prometheus#16355) - \[CHANGE] UI: Hide expanded alert annotations by default, enabling more information density on the `/alerts` page. [#17611](prometheus/prometheus#17611) - \[FEATURE] AWS SD: Add MSK Role. [#17600](prometheus/prometheus#17600) - \[FEATURE] PromQL: Add `fill()` / `fill_left()` / `fill_right()` binop modifiers for specifying default values for missing series. [#17644](prometheus/prometheus#17644) - \[FEATURE] Web: Add OpenAPI 3.2 specification for the HTTP API at `/api/v1/openapi.yaml`. [#17825](prometheus/prometheus#17825) - \[FEATURE] Dockerfile: Add distroless image variant using UID/GID 65532 and no VOLUME declaration. Busybox image remains default. [#17876](prometheus/prometheus#17876) - \[FEATURE] Web: Add on-demand wall time profiling under `<URL>/debug/pprof/fgprof`. [#18027](prometheus/prometheus#18027) - \[ENHANCEMENT] PromQL: Add more detail to histogram quantile monotonicity info annotations. [#15578](prometheus/prometheus#15578) - \[ENHANCEMENT] Alerting: Independent alertmanager sendloops. [#16355](prometheus/prometheus#16355) - \[ENHANCEMENT] TSDB: Experimental support for early compaction of stale series in the memory with configurable threshold `stale_series_compaction_threshold` in the config file. [#16929](prometheus/prometheus#16929) - \[ENHANCEMENT] Service Discovery: Service discoveries are now removable from the Prometheus binary through the Go build tag `remove_all_sd` and individual service discoveries can be re-added with the build tags `enable_<sd name>_sd`. Users can build a custom Prometheus with only the necessary SDs for a smaller binary size. [#17736](prometheus/prometheus#17736) - \[ENHANCEMENT] Promtool: Support promql syntax features `promql-duration-expr` and `promql-extended-range-selectors`. [#17926](prometheus/prometheus#17926) - \[PERF] PromQL: Avoid unnecessary label extraction in PromQL functions. [#17676](prometheus/prometheus#17676) - \[PERF] PromQL: Improve performance of regex matchers like `.*-.*-.*`. [#17707](prometheus/prometheus#17707) - \[PERF] OTLP: Add label caching for OTLP-to-Prometheus conversion to reduce allocations and improve latency. [#17860](prometheus/prometheus#17860) - \[PERF] API: Compute `/api/v1/targets/relabel_steps` in a single pass instead of re-running relabeling for each prefix. [#17969](prometheus/prometheus#17969) - \[PERF] tsdb: Optimize LabelValues intersection performance for matchers. [#18069](prometheus/prometheus#18069) - \[BUGFIX] PromQL: Prevent query strings containing only UTF-8 continuation bytes from crashing Prometheus. [#17735](prometheus/prometheus#17735) - \[BUGFIX] Web: Fix missing `X-Prometheus-Stopping` header for `/-/ready` endpoint in `NotReady` state. [#17795](prometheus/prometheus#17795) - \[BUGFIX] PromQL: Fix PromQL `info()` function returning empty results when filtering by a label that exists on both the input metric and `target_info`. [#17817](prometheus/prometheus#17817) - \[BUGFIX] TSDB: Fix a bug during exemplar buffer grow/shrink that could cause exemplars to be incorrectly discarded. [#17863](prometheus/prometheus#17863) - \[BUGFIX] UI: Fix broken graph display after page reload, due to broken Y axis min encoding/decoding. [#17869](prometheus/prometheus#17869) - \[BUGFIX] TSDB: Fix memory leaks in buffer pools by clearing reference fields (Labels, Histogram pointers, metadata strings) before returning buffers to pools. [#17879](prometheus/prometheus#17879) - \[BUGFIX] PromQL: info function: fix series without identifying labels not being returned. [#17898](prometheus/prometheus#17898) - \[BUGFIX] OTLP: Filter `__name__` from OTLP attributes to prevent duplicate labels. [#17917](prometheus/prometheus#17917) - \[BUGFIX] TSDB: Fix division by zero when computing stale series ratio with empty head. [#17952](prometheus/prometheus#17952) - \[BUGFIX] OTLP: Fix potential silent data loss for sum metrics. [#17954](prometheus/prometheus#17954) - \[BUGFIX] PromQL: Fix smoothed interpolation across counter resets. [#17988](prometheus/prometheus#17988) - \[BUGFIX] PromQL: Fix panic with `@` modifier on empty ranges. [#18020](prometheus/prometheus#18020) - \[BUGFIX] PromQL: Fix `avg_over_time` for a single native histogram. [#18058](prometheus/prometheus#18058)

roidelapluie force-pushed the roidelapluie/openapi branch 5 times, most recently from d86390b to 8ea23c6 Compare January 9, 2026 14:39

roidelapluie mentioned this pull request Jan 9, 2026

Consider keeping go to 1.24 in go.mod pb33f/libopenapi#504

Closed

roidelapluie force-pushed the roidelapluie/openapi branch 6 times, most recently from a87a421 to 2126d70 Compare January 9, 2026 16:45

roidelapluie requested a review from juliusv as a code owner January 9, 2026 16:45

roidelapluie force-pushed the roidelapluie/openapi branch from 70a455d to cda1940 Compare January 12, 2026 10:12

roidelapluie force-pushed the roidelapluie/openapi branch from cda1940 to fec31da Compare January 12, 2026 11:31

krajorama self-assigned this Jan 20, 2026

krajorama reviewed Jan 20, 2026

View reviewed changes

bwplotka reviewed Jan 20, 2026

View reviewed changes

roidelapluie force-pushed the roidelapluie/openapi branch from fec31da to cf85d99 Compare January 21, 2026 10:45

krajorama reviewed Jan 27, 2026

View reviewed changes

web/api/v1/openapi_examples.go Outdated Show resolved Hide resolved

roidelapluie requested a review from a team as a code owner January 28, 2026 10:10

krajorama approved these changes Jan 29, 2026

View reviewed changes

roidelapluie added 5 commits January 29, 2026 10:01

Add OpenAPI 3.1 support with version selection

5dcc56c

Add support for both OpenAPI 3.1 and 3.2 specifications with version selection via openapi_version query parameter. Defaults to 3.1 for broader compatibility Signed-off-by: Julien Pivotto <[email protected]>

OpenAPI: Add minimum coverage test

98c2575

Signed-off-by: Julien Pivotto <[email protected]>

roidelapluie force-pushed the roidelapluie/openapi branch 4 times, most recently from 1eab834 to 8c46c60 Compare January 29, 2026 11:07

OpenAPI: Improve examples handling

8571281

Signed-off-by: Julien Pivotto <[email protected]>

roidelapluie force-pushed the roidelapluie/openapi branch from 8c46c60 to 8571281 Compare January 29, 2026 11:18

roidelapluie merged commit 75f9490 into prometheus:main Jan 29, 2026
32 checks passed

roidelapluie added a commit to roidelapluie/prometheus that referenced this pull request Jan 29, 2026

Features API: Add OpenAPI 3.1 and 3.2

b204f77

Now that prometheus#17825 is merged. Signed-off-by: Julien Pivotto <[email protected]>

roidelapluie mentioned this pull request Jan 29, 2026

Features API: Add OpenAPI 3.1 and 3.2 #17970

Merged

roidelapluie added a commit to roidelapluie/prometheus that referenced this pull request Jan 29, 2026

Features API: Add OpenAPI 3.1 and 3.2

3bc688e

Now that prometheus#17825 is merged. Signed-off-by: Julien Pivotto <[email protected]>

SuperQ reviewed Feb 11, 2026

View reviewed changes

ArthurSens mentioned this pull request Mar 6, 2026

[CHORE] Bump Prometheus dependency to 3.10 open-telemetry/opentelemetry-collector-contrib#46732

Merged

github-actions bot mentioned this pull request Mar 19, 2026

Update prom/prometheus Docker tag to v3.10.0 claytono/infra#1704

Merged

1 task

Conversation

roidelapluie commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue(s) does the PR fix:

Does this PR introduce a user-facing change?

Uh oh!

juliusv commented Jan 12, 2026

Uh oh!

krajorama left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

krajorama left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bwplotka left a comment

Choose a reason for hiding this comment

Uh oh!

krajorama left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

roidelapluie commented Jan 28, 2026

Uh oh!

krajorama left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SuperQ Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

roidelapluie Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

roidelapluie Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

roidelapluie commented Jan 9, 2026 •

edited

Loading