Add OpenAPI 3.2 specification generation for Prometheus HTTP API#17825
Merged
roidelapluie merged 6 commits intoprometheus:mainfrom Jan 29, 2026
Merged
Add OpenAPI 3.2 specification generation for Prometheus HTTP API#17825roidelapluie merged 6 commits intoprometheus:mainfrom
roidelapluie merged 6 commits intoprometheus:mainfrom
Conversation
d86390b to
8ea23c6
Compare
a87a421 to
2126d70
Compare
70a455d to
cda1940
Compare
Member
cda1940 to
fec31da
Compare
bwplotka
reviewed
Jan 20, 2026
Member
bwplotka
left a comment
There was a problem hiding this comment.
Amazing work
Did you try generate Go client for this? Curious if we can finally replace client_golang api package 🤔
fec31da to
cf85d99
Compare
krajorama
reviewed
Jan 27, 2026
Member
krajorama
left a comment
There was a problem hiding this comment.
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.
Member
Author
|
I gene
I generated https://github.com/roidelapluie/promclient |
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 <291750+roidelapluie@users.noreply.github.com>
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 <291750+roidelapluie@users.noreply.github.com>
- 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 <291750+roidelapluie@users.noreply.github.com>
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 <291750+roidelapluie@users.noreply.github.com>
Signed-off-by: Julien Pivotto <291750+roidelapluie@users.noreply.github.com>
1eab834 to
8c46c60
Compare
Signed-off-by: Julien Pivotto <291750+roidelapluie@users.noreply.github.com>
8c46c60 to
8571281
Compare
roidelapluie
added a commit
to roidelapluie/prometheus
that referenced
this pull request
Jan 29, 2026
Now that prometheus#17825 is merged. Signed-off-by: Julien Pivotto <291750+roidelapluie@users.noreply.github.com>
roidelapluie
added a commit
to roidelapluie/prometheus
that referenced
this pull request
Jan 29, 2026
Now that prometheus#17825 is merged. Signed-off-by: Julien Pivotto <291750+roidelapluie@users.noreply.github.com>
SuperQ
reviewed
Feb 11, 2026
| module github.com/prometheus/prometheus | ||
|
|
||
| go 1.24.0 | ||
| go 1.25.0 |
Member
There was a problem hiding this comment.
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.
Member
Author
There was a problem hiding this comment.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
Testing:
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?