Add Swagger 2.0 documentation for Prysm API endpoints

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

@@ -26,6 +26,15 @@ import (
 
 // GetWeakSubjectivity computes the starting epoch of the current weak subjectivity period, and then also
 // determines the best block root and state root to use for a Checkpoint Sync starting from that point.
+//
+// @Summary Get weak subjectivity checkpoint
+// @Description Computes the weak subjectivity checkpoint for safe checkpoint sync initialization
+// @Tags Prysm Beacon
+// @Produce json
+// @Success 200 {object} structs.GetWeakSubjectivityResponse
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Failure 503 {object} httputil.DefaultJsonError "Beacon node is currently syncing"
+// @Router /prysm/v1/beacon/weak_subjectivity [get]
 func (s *Server) GetWeakSubjectivity(w http.ResponseWriter, r *http.Request) {
 	ctx, span := trace.StartSpan(r.Context(), "beacon.GetWeakSubjectivity")
 	defer span.End()
@@ -79,6 +88,17 @@ func (s *Server) GetWeakSubjectivity(w http.ResponseWriter, r *http.Request) {
 }
 
 // GetIndividualVotes returns a list of validators individual vote status of a given epoch.
+//
+// @Summary Get individual validator votes
+// @Description Returns detailed voting information for specified validators in a given epoch
+// @Tags Prysm Beacon
+// @Accept json
+// @Produce json
+// @Param request body structs.GetIndividualVotesRequest true "Validator indices/public keys and epoch"
+// @Success 200 {object} structs.GetIndividualVotesResponse
+// @Failure 400 {object} httputil.DefaultJsonError
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Router /prysm/v1/beacon/individual_votes [post]
 func (s *Server) GetIndividualVotes(w http.ResponseWriter, r *http.Request) {
 	ctx, span := trace.StartSpan(r.Context(), "validator.GetIndividualVotes")
 	defer span.End()
@@ -159,6 +179,14 @@ func (s *Server) GetIndividualVotes(w http.ResponseWriter, r *http.Request) {
 
 // GetChainHead retrieves information about the head of the beacon chain from
 // the view of the beacon chain node.
+//
+// @Summary Get chain head information
+// @Description Returns detailed information about the current head, finalized, and justified checkpoints of the beacon chain
+// @Tags Prysm Beacon
+// @Produce json
+// @Success 200 {object} structs.ChainHead
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Router /prysm/v1/beacon/chain_head [get]
 func (s *Server) GetChainHead(w http.ResponseWriter, r *http.Request) {
 	ctx, span := trace.StartSpan(r.Context(), "beacon.GetChainHead")
 	defer span.End()
@@ -186,7 +214,20 @@ func (s *Server) GetChainHead(w http.ResponseWriter, r *http.Request) {
 	httputil.WriteJson(w, response)
 }
 
+// PublishBlobs publishes blob sidecars to the network.
 // Warning: no longer supported post Fulu blobs
+//
+// @Summary Publish blob sidecars (DEPRECATED post-Fulu)
+// @Description Publishes blob sidecars to the beacon network. Only supported for Deneb through Fulu epochs.
+// @Tags Prysm Beacon
+// @Accept json
+// @Param request body structs.PublishBlobsRequest true "Blob sidecars to publish"
+// @Success 200 "Blobs successfully published"
+// @Failure 400 {object} httputil.DefaultJsonError
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Failure 503 {object} httputil.DefaultJsonError "Beacon node is currently syncing"
+// @Deprecated
+// @Router /prysm/v1/beacon/blobs [post]
 func (s *Server) PublishBlobs(w http.ResponseWriter, r *http.Request) {
 	ctx, span := trace.StartSpan(r.Context(), "beacon.PublishBlobs")
 	defer span.End()

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

@@ -19,6 +19,19 @@ import (
 
 // QueryBeaconState handles SSZ Query request for BeaconState.
 // Returns as bytes serialized SSZQueryResponse.
+//
+// @Summary Query beacon state with SSZ path
+// @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.
+// @Tags Prysm Beacon
+// @Accept json
+// @Produce application/octet-stream
+// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)"
+// @Param request body structs.SSZQueryRequest true "SSZ query path (e.g., 'validators[0].pubkey')"
+// @Success 200 {string} binary "SSZ-encoded SSZQueryResponse containing root and result"
+// @Failure 400 {object} httputil.DefaultJsonError
+// @Failure 404 {object} httputil.DefaultJsonError
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Router /prysm/v1/beacon/states/{state_id}/query [post]
 func (s *Server) QueryBeaconState(w http.ResponseWriter, r *http.Request) {
 	ctx, span := trace.StartSpan(r.Context(), "beacon.QueryBeaconState")
 	defer span.End()
@@ -110,8 +123,21 @@ func (s *Server) QueryBeaconState(w http.ResponseWriter, r *http.Request) {
 	httputil.WriteSsz(w, responseSsz)
 }
 
-// QueryBeaconState handles SSZ Query request for BeaconState.
+// QueryBeaconBlock handles SSZ Query request for BeaconBlock.
 // Returns as bytes serialized SSZQueryResponse.
+//
+// @Summary Query beacon block with SSZ path
+// @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.
+// @Tags Prysm Beacon
+// @Accept json
+// @Produce application/octet-stream
+// @Param block_id path string true "Block identifier (head, genesis, finalized, slot number, or hex root)"
+// @Param request body structs.SSZQueryRequest true "SSZ query path (e.g., 'body.attestations[0]')"
+// @Success 200 {string} binary "SSZ-encoded SSZQueryResponse containing root and result"
+// @Failure 400 {object} httputil.DefaultJsonError
+// @Failure 404 {object} httputil.DefaultJsonError
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Router /prysm/v1/beacon/blocks/{block_id}/query [post]
 func (s *Server) QueryBeaconBlock(w http.ResponseWriter, r *http.Request) {
 	ctx, span := trace.StartSpan(r.Context(), "beacon.QueryBeaconBlock")
 	defer span.End()

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

@@ -48,6 +48,19 @@ import (
 //			}
 //		]
 //	}
+//
+// @Summary Get validator count by status
+// @Description Returns the total number of validators grouped by their status (active, pending, exited, withdrawal, etc.) for a given state
+// @Tags Prysm Beacon
+// @Produce json
+// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)"
+// @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"
+// @Success 200 {object} structs.GetValidatorCountResponse
+// @Failure 400 {object} httputil.DefaultJsonError
+// @Failure 404 {object} httputil.DefaultJsonError
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Router /prysm/v1/beacon/states/{state_id}/validator_count [get]
+// @Router /eth/v1/beacon/states/{state_id}/validator_count [get]
 func (s *Server) GetValidatorCount(w http.ResponseWriter, r *http.Request) {
 	ctx, span := trace.StartSpan(r.Context(), "beacon.GetValidatorCount")
 	defer span.End()

beacon-chain/rpc/prysm/doc.go

@@ -0,0 +1,18 @@
+// Package prysm provides custom Prysm beacon node API endpoints.
+//
+// @title Prysm Beacon Node Custom API
+// @version 1.0
+// @description Custom Prysm endpoints for beacon node operations, validator metrics, and extended functionality.
+// @description These endpoints extend the standard Ethereum Beacon Node API with Prysm-specific features.
+//
+// @contact.name Prysm Team
+// @contact.url https://github.com/OffchainLabs/prysm
+//
+// @license.name GPL-3.0
+// @license.url https://github.com/OffchainLabs/prysm/blob/develop/LICENSE.md
+//
+// @host localhost:3500
+// @BasePath /
+//
+// @schemes http https
+package prysm

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

@@ -19,6 +19,14 @@ import (
 )
 
 // ListTrustedPeer retrieves data about the node's trusted peers.
+//
+// @Summary List trusted peers
+// @Description Returns a list of all trusted peers configured on this beacon node, including their connection state, direction, ENR, and last seen address
+// @Tags Prysm Node
+// @Produce json
+// @Success 200 {object} structs.PeersResponse
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Router /prysm/node/trusted_peers [get]
 func (s *Server) ListTrustedPeer(w http.ResponseWriter, r *http.Request) {
 	_, span := trace.StartSpan(r.Context(), "node.ListTrustedPeer")
 	defer span.End()
@@ -53,6 +61,16 @@ func (s *Server) ListTrustedPeer(w http.ResponseWriter, r *http.Request) {
 }
 
 // AddTrustedPeer adds a new peer into node's trusted peer set by Multiaddr
+//
+// @Summary Add a trusted peer
+// @Description Adds a peer to the beacon node's trusted peer set using its multiaddress. Trusted peers are given priority in peer connections.
+// @Tags Prysm Node
+// @Accept json
+// @Param request body structs.AddrRequest true "Peer multiaddress (e.g., /ip4/127.0.0.1/tcp/13000/p2p/16Uiu2...)"
+// @Success 200 "Peer successfully added to trusted set"
+// @Failure 400 {object} httputil.DefaultJsonError
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Router /prysm/node/trusted_peers [post]
 func (s *Server) AddTrustedPeer(w http.ResponseWriter, r *http.Request) {
 	_, span := trace.StartSpan(r.Context(), "node.AddTrustedPeer")
 	defer span.End()
@@ -101,6 +119,14 @@ func (s *Server) AddTrustedPeer(w http.ResponseWriter, r *http.Request) {
 }
 
 // RemoveTrustedPeer removes peer from our trusted peer set but does not close connection.
+//
+// @Summary Remove a trusted peer
+// @Description Removes a peer from the beacon node's trusted peer set by peer ID. Does not disconnect the peer if already connected.
+// @Tags Prysm Node
+// @Param peer_id path string true "Peer ID to remove from trusted set"
+// @Success 200 "Peer successfully removed from trusted set"
+// @Failure 400 {object} httputil.DefaultJsonError
+// @Router /prysm/node/trusted_peers/{peer_id} [delete]
 func (s *Server) RemoveTrustedPeer(w http.ResponseWriter, r *http.Request) {
 	_, span := trace.StartSpan(r.Context(), "node.RemoveTrustedPeer")
 	defer span.End()

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

@@ -17,6 +17,17 @@ import (
 // GetParticipation retrieves the validator participation information for a given epoch,
 // it returns the information about validator's participation rate in voting on the proof of stake
 // rules based on their balance compared to the total active validator balance.
+//
+// @Summary Get validator participation for an epoch
+// @Description Returns participation rate information for validators at a given state, including voting statistics and balance information for current and previous epochs
+// @Tags Prysm Validator
+// @Produce json
+// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)"
+// @Success 200 {object} structs.GetValidatorParticipationResponse
+// @Failure 400 {object} httputil.DefaultJsonError
+// @Failure 404 {object} httputil.DefaultJsonError
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Router /prysm/v1/validators/{state_id}/participation [get]
 func (s *Server) GetParticipation(w http.ResponseWriter, r *http.Request) {
 	ctx, span := trace.StartSpan(r.Context(), "validator.GetParticipation")
 	defer span.End()
@@ -62,6 +73,17 @@ func (s *Server) GetParticipation(w http.ResponseWriter, r *http.Request) {
 //
 // This data includes any activations, voluntary exits, and involuntary
 // ejections.
+//
+// @Summary Get active validator set changes
+// @Description Returns validator set changes for a given epoch including activations, voluntary exits, slashings, and ejections with both public keys and indices
+// @Tags Prysm Validator
+// @Produce json
+// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)"
+// @Success 200 {object} structs.ActiveSetChanges
+// @Failure 400 {object} httputil.DefaultJsonError
+// @Failure 404 {object} httputil.DefaultJsonError
+// @Failure 500 {object} httputil.DefaultJsonError
+// @Router /prysm/v1/validators/{state_id}/active_set_changes [get]
 func (s *Server) GetActiveSetChanges(w http.ResponseWriter, r *http.Request) {
 	ctx, span := trace.StartSpan(r.Context(), "validator.GetActiveSetChanges")
 	defer span.End()

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

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

changelog/willianpaixao_swagger.md

@@ -0,0 +1,3 @@
+### Added
+
+- Added Swagger 2.0 documentation for all Prysm API endpoints, including machine-readable OpenAPI specifications (swagger.yaml, swagger.json)