Skip to content

Commit 0f565e0

Browse files
willianpaixaowillianpaixao
committed
Add Swagger 2.0 documentation for Prysm API endpoints
This commit implements API documentation for all custom Prysm endpoints using swaggo/swag, addressing GitHub issue #12794. Changes: - Added Swagger annotations endpoint handlers - Generated swagger.yaml, swagger.json, and docs.go in /docs directory Swagger generation command: swag init --parseDependency --parseInternal --generalInfo doc.go \ --dir ./beacon-chain/rpc/prysm,./api/server/structs,./network/httputil,./consensus-types/primitives \ --output ./docs Technical notes: - All annotations use simple package names - No handler logic changes, only doc comments added Closes: #12794 Signed-off-by: Willian Paixao <[email protected]>
1 parent 2a23dc7 commit 0f565e0

File tree

13 files changed

+3391
-28
lines changed

13 files changed

+3391
-28
lines changed

‎beacon-chain/rpc/prysm/beacon/handlers.go‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,15 @@ import (
2626

2727
// GetWeakSubjectivity computes the starting epoch of the current weak subjectivity period, and then also
2828
// determines the best block root and state root to use for a Checkpoint Sync starting from that point.
29+
//
30+
// @Summary Get weak subjectivity checkpoint
31+
// @Description Computes the weak subjectivity checkpoint for safe checkpoint sync initialization
32+
// @Tags Prysm Beacon
33+
// @Produce json
34+
// @Success 200 {object} structs.GetWeakSubjectivityResponse
35+
// @Failure 500 {object} httputil.DefaultJsonError
36+
// @Failure 503 {object} httputil.DefaultJsonError "Beacon node is currently syncing"
37+
// @Router /prysm/v1/beacon/weak_subjectivity [get]
2938
func (s *Server) GetWeakSubjectivity(w http.ResponseWriter, r *http.Request) {
3039
ctx, span := trace.StartSpan(r.Context(), "beacon.GetWeakSubjectivity")
3140
defer span.End()
@@ -79,6 +88,17 @@ func (s *Server) GetWeakSubjectivity(w http.ResponseWriter, r *http.Request) {
7988
}
8089

8190
// GetIndividualVotes returns a list of validators individual vote status of a given epoch.
91+
//
92+
// @Summary Get individual validator votes
93+
// @Description Returns detailed voting information for specified validators in a given epoch
94+
// @Tags Prysm Beacon
95+
// @Accept json
96+
// @Produce json
97+
// @Param request body structs.GetIndividualVotesRequest true "Validator indices/public keys and epoch"
98+
// @Success 200 {object} structs.GetIndividualVotesResponse
99+
// @Failure 400 {object} httputil.DefaultJsonError
100+
// @Failure 500 {object} httputil.DefaultJsonError
101+
// @Router /prysm/v1/beacon/individual_votes [post]
82102
func (s *Server) GetIndividualVotes(w http.ResponseWriter, r *http.Request) {
83103
ctx, span := trace.StartSpan(r.Context(), "validator.GetIndividualVotes")
84104
defer span.End()
@@ -159,6 +179,14 @@ func (s *Server) GetIndividualVotes(w http.ResponseWriter, r *http.Request) {
159179

160180
// GetChainHead retrieves information about the head of the beacon chain from
161181
// the view of the beacon chain node.
182+
//
183+
// @Summary Get chain head information
184+
// @Description Returns detailed information about the current head, finalized, and justified checkpoints of the beacon chain
185+
// @Tags Prysm Beacon
186+
// @Produce json
187+
// @Success 200 {object} structs.ChainHead
188+
// @Failure 500 {object} httputil.DefaultJsonError
189+
// @Router /prysm/v1/beacon/chain_head [get]
162190
func (s *Server) GetChainHead(w http.ResponseWriter, r *http.Request) {
163191
ctx, span := trace.StartSpan(r.Context(), "beacon.GetChainHead")
164192
defer span.End()
@@ -186,7 +214,20 @@ func (s *Server) GetChainHead(w http.ResponseWriter, r *http.Request) {
186214
httputil.WriteJson(w, response)
187215
}
188216

217+
// PublishBlobs publishes blob sidecars to the network.
189218
// Warning: no longer supported post Fulu blobs
219+
//
220+
// @Summary Publish blob sidecars (DEPRECATED post-Fulu)
221+
// @Description Publishes blob sidecars to the beacon network. Only supported for Deneb through Fulu epochs.
222+
// @Tags Prysm Beacon
223+
// @Accept json
224+
// @Param request body structs.PublishBlobsRequest true "Blob sidecars to publish"
225+
// @Success 200 "Blobs successfully published"
226+
// @Failure 400 {object} httputil.DefaultJsonError
227+
// @Failure 500 {object} httputil.DefaultJsonError
228+
// @Failure 503 {object} httputil.DefaultJsonError "Beacon node is currently syncing"
229+
// @Deprecated
230+
// @Router /prysm/v1/beacon/blobs [post]
190231
func (s *Server) PublishBlobs(w http.ResponseWriter, r *http.Request) {
191232
ctx, span := trace.StartSpan(r.Context(), "beacon.PublishBlobs")
192233
defer span.End()

‎beacon-chain/rpc/prysm/beacon/ssz_query.go‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,19 @@ import (
1919

2020
// QueryBeaconState handles SSZ Query request for BeaconState.
2121
// Returns as bytes serialized SSZQueryResponse.
22+
//
23+
// @Summary Query beacon state with SSZ path
24+
// @Description Executes an SSZ query on a beacon state and returns the result as SSZ-encoded bytes. Allows efficient extraction of specific fields from large state objects.
25+
// @Tags Prysm Beacon
26+
// @Accept json
27+
// @Produce application/octet-stream
28+
// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)"
29+
// @Param request body structs.SSZQueryRequest true "SSZ query path (e.g., 'validators[0].pubkey')"
30+
// @Success 200 {string} binary "SSZ-encoded SSZQueryResponse containing root and result"
31+
// @Failure 400 {object} httputil.DefaultJsonError
32+
// @Failure 404 {object} httputil.DefaultJsonError
33+
// @Failure 500 {object} httputil.DefaultJsonError
34+
// @Router /prysm/v1/beacon/states/{state_id}/query [post]
2235
func (s *Server) QueryBeaconState(w http.ResponseWriter, r *http.Request) {
2336
ctx, span := trace.StartSpan(r.Context(), "beacon.QueryBeaconState")
2437
defer span.End()
@@ -110,8 +123,21 @@ func (s *Server) QueryBeaconState(w http.ResponseWriter, r *http.Request) {
110123
httputil.WriteSsz(w, responseSsz)
111124
}
112125

113-
// QueryBeaconState handles SSZ Query request for BeaconState.
126+
// QueryBeaconBlock handles SSZ Query request for BeaconBlock.
114127
// Returns as bytes serialized SSZQueryResponse.
128+
//
129+
// @Summary Query beacon block with SSZ path
130+
// @Description Executes an SSZ query on a beacon block and returns the result as SSZ-encoded bytes. Allows efficient extraction of specific fields from block objects.
131+
// @Tags Prysm Beacon
132+
// @Accept json
133+
// @Produce application/octet-stream
134+
// @Param block_id path string true "Block identifier (head, genesis, finalized, slot number, or hex root)"
135+
// @Param request body structs.SSZQueryRequest true "SSZ query path (e.g., 'body.attestations[0]')"
136+
// @Success 200 {string} binary "SSZ-encoded SSZQueryResponse containing root and result"
137+
// @Failure 400 {object} httputil.DefaultJsonError
138+
// @Failure 404 {object} httputil.DefaultJsonError
139+
// @Failure 500 {object} httputil.DefaultJsonError
140+
// @Router /prysm/v1/beacon/blocks/{block_id}/query [post]
115141
func (s *Server) QueryBeaconBlock(w http.ResponseWriter, r *http.Request) {
116142
ctx, span := trace.StartSpan(r.Context(), "beacon.QueryBeaconBlock")
117143
defer span.End()

‎beacon-chain/rpc/prysm/beacon/validator_count.go‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,19 @@ import (
4848
// }
4949
// ]
5050
// }
51+
//
52+
// @Summary Get validator count by status
53+
// @Description Returns the total number of validators grouped by their status (active, pending, exited, withdrawal, etc.) for a given state
54+
// @Tags Prysm Beacon
55+
// @Produce json
56+
// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)"
57+
// @Param status query []string false "Validator status filter (can be repeated). If omitted, returns counts for all statuses. Valid values: pending_initialized, pending_queued, active_ongoing, active_exiting, active_slashed, exited_unslashed, exited_slashed, withdrawal_possible, withdrawal_done, active, pending, exited, withdrawal"
58+
// @Success 200 {object} structs.GetValidatorCountResponse
59+
// @Failure 400 {object} httputil.DefaultJsonError
60+
// @Failure 404 {object} httputil.DefaultJsonError
61+
// @Failure 500 {object} httputil.DefaultJsonError
62+
// @Router /prysm/v1/beacon/states/{state_id}/validator_count [get]
63+
// @Router /eth/v1/beacon/states/{state_id}/validator_count [get]
5164
func (s *Server) GetValidatorCount(w http.ResponseWriter, r *http.Request) {
5265
ctx, span := trace.StartSpan(r.Context(), "beacon.GetValidatorCount")
5366
defer span.End()

‎beacon-chain/rpc/prysm/doc.go‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Package prysm provides custom Prysm beacon node API endpoints.
2+
//
3+
// @title Prysm Beacon Node Custom API
4+
// @version 1.0
5+
// @description Custom Prysm endpoints for beacon node operations, validator metrics, and extended functionality.
6+
// @description These endpoints extend the standard Ethereum Beacon Node API with Prysm-specific features.
7+
//
8+
// @contact.name Prysm Team
9+
// @contact.url https://github.com/OffchainLabs/prysm
10+
//
11+
// @license.name GPL-3.0
12+
// @license.url https://github.com/OffchainLabs/prysm/blob/develop/LICENSE.md
13+
//
14+
// @host localhost:3500
15+
// @BasePath /
16+
//
17+
// @schemes http https
18+
package prysm

‎beacon-chain/rpc/prysm/node/handlers.go‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,14 @@ import (
1919
)
2020

2121
// ListTrustedPeer retrieves data about the node's trusted peers.
22+
//
23+
// @Summary List trusted peers
24+
// @Description Returns a list of all trusted peers configured on this beacon node, including their connection state, direction, ENR, and last seen address
25+
// @Tags Prysm Node
26+
// @Produce json
27+
// @Success 200 {object} structs.PeersResponse
28+
// @Failure 500 {object} httputil.DefaultJsonError
29+
// @Router /prysm/node/trusted_peers [get]
2230
func (s *Server) ListTrustedPeer(w http.ResponseWriter, r *http.Request) {
2331
_, span := trace.StartSpan(r.Context(), "node.ListTrustedPeer")
2432
defer span.End()
@@ -53,6 +61,16 @@ func (s *Server) ListTrustedPeer(w http.ResponseWriter, r *http.Request) {
5361
}
5462

5563
// AddTrustedPeer adds a new peer into node's trusted peer set by Multiaddr
64+
//
65+
// @Summary Add a trusted peer
66+
// @Description Adds a peer to the beacon node's trusted peer set using its multiaddress. Trusted peers are given priority in peer connections.
67+
// @Tags Prysm Node
68+
// @Accept json
69+
// @Param request body structs.AddrRequest true "Peer multiaddress (e.g., /ip4/127.0.0.1/tcp/13000/p2p/16Uiu2...)"
70+
// @Success 200 "Peer successfully added to trusted set"
71+
// @Failure 400 {object} httputil.DefaultJsonError
72+
// @Failure 500 {object} httputil.DefaultJsonError
73+
// @Router /prysm/node/trusted_peers [post]
5674
func (s *Server) AddTrustedPeer(w http.ResponseWriter, r *http.Request) {
5775
_, span := trace.StartSpan(r.Context(), "node.AddTrustedPeer")
5876
defer span.End()
@@ -101,6 +119,14 @@ func (s *Server) AddTrustedPeer(w http.ResponseWriter, r *http.Request) {
101119
}
102120

103121
// RemoveTrustedPeer removes peer from our trusted peer set but does not close connection.
122+
//
123+
// @Summary Remove a trusted peer
124+
// @Description Removes a peer from the beacon node's trusted peer set by peer ID. Does not disconnect the peer if already connected.
125+
// @Tags Prysm Node
126+
// @Param peer_id path string true "Peer ID to remove from trusted set"
127+
// @Success 200 "Peer successfully removed from trusted set"
128+
// @Failure 400 {object} httputil.DefaultJsonError
129+
// @Router /prysm/node/trusted_peers/{peer_id} [delete]
104130
func (s *Server) RemoveTrustedPeer(w http.ResponseWriter, r *http.Request) {
105131
_, span := trace.StartSpan(r.Context(), "node.RemoveTrustedPeer")
106132
defer span.End()

‎beacon-chain/rpc/prysm/validator/handlers.go‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,17 @@ import (
1717
// GetParticipation retrieves the validator participation information for a given epoch,
1818
// it returns the information about validator's participation rate in voting on the proof of stake
1919
// rules based on their balance compared to the total active validator balance.
20+
//
21+
// @Summary Get validator participation for an epoch
22+
// @Description Returns participation rate information for validators at a given state, including voting statistics and balance information for current and previous epochs
23+
// @Tags Prysm Validator
24+
// @Produce json
25+
// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)"
26+
// @Success 200 {object} structs.GetValidatorParticipationResponse
27+
// @Failure 400 {object} httputil.DefaultJsonError
28+
// @Failure 404 {object} httputil.DefaultJsonError
29+
// @Failure 500 {object} httputil.DefaultJsonError
30+
// @Router /prysm/v1/validators/{state_id}/participation [get]
2031
func (s *Server) GetParticipation(w http.ResponseWriter, r *http.Request) {
2132
ctx, span := trace.StartSpan(r.Context(), "validator.GetParticipation")
2233
defer span.End()
@@ -62,6 +73,17 @@ func (s *Server) GetParticipation(w http.ResponseWriter, r *http.Request) {
6273
//
6374
// This data includes any activations, voluntary exits, and involuntary
6475
// ejections.
76+
//
77+
// @Summary Get active validator set changes
78+
// @Description Returns validator set changes for a given epoch including activations, voluntary exits, slashings, and ejections with both public keys and indices
79+
// @Tags Prysm Validator
80+
// @Produce json
81+
// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)"
82+
// @Success 200 {object} structs.ActiveSetChanges
83+
// @Failure 400 {object} httputil.DefaultJsonError
84+
// @Failure 404 {object} httputil.DefaultJsonError
85+
// @Failure 500 {object} httputil.DefaultJsonError
86+
// @Router /prysm/v1/validators/{state_id}/active_set_changes [get]
6587
func (s *Server) GetActiveSetChanges(w http.ResponseWriter, r *http.Request) {
6688
ctx, span := trace.StartSpan(r.Context(), "validator.GetActiveSetChanges")
6789
defer span.End()

‎beacon-chain/rpc/prysm/validator/validator_performance.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,17 @@ import (
1414
)
1515

1616
// GetPerformance is an HTTP handler for GetPerformance.
17+
//
18+
// @Summary Get validator performance metrics
19+
// @Description Returns detailed performance metrics for specified validators including voting accuracy, balances before and after epoch transitions, and inactivity scores
20+
// @Tags Prysm Validator
21+
// @Accept json
22+
// @Produce json
23+
// @Param request body structs.GetValidatorPerformanceRequest true "Validator public keys and/or indices to query"
24+
// @Success 200 {object} structs.GetValidatorPerformanceResponse
25+
// @Failure 400 {object} httputil.DefaultJsonError
26+
// @Failure 500 {object} httputil.DefaultJsonError
27+
// @Router /prysm/validators/performance [post]
1728
func (s *Server) GetPerformance(w http.ResponseWriter, r *http.Request) {
1829
ctx, span := trace.StartSpan(r.Context(), "validator.GetPerformance")
1930
defer span.End()

‎changelog/willianpaixao_swagger.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
### Added
2+
3+
- Added Swagger 2.0 documentation for all Prysm API endpoints, including machine-readable OpenAPI specifications (swagger.yaml, swagger.json)

0 commit comments

Comments
 (0)