Add Swagger 2.0 documentation for Prysm API endpoints #16080
Conversation
This commit implements API documentation for all custom Prysm endpoints using swaggo/swag, addressing GitHub issue OffchainLabs#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: OffchainLabs#12794 Signed-off-by: Willian Paixao <[email protected]>
|
|
There was a problem hiding this comment.
Pull request overview
This PR adds Swagger 2.0 documentation for 14 custom Prysm API endpoints using swaggo/swag annotation-based documentation generation. The endpoints span beacon node operations (/prysm/v1/beacon/*), validator metrics (/prysm/v1/validators/*, /prysm/validators/performance), and node management (/prysm/node/trusted_peers). This documentation enables API discoverability, interactive exploration via Swagger UI, and potential client SDK generation.
Key Changes:
- Added swaggo/swag v1.16.6 dependency for Swagger generation
- Added Swagger annotations to 14 HTTP handler functions across beacon, validator, and node packages
- Generated machine-readable OpenAPI 2.0 specifications (swagger.yaml, swagger.json, docs.go)
Reviewed changes
Copilot reviewed 12 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| go.mod | Added swaggo/swag dependency and updated several unrelated dependencies |
| go.sum | Transitive dependency checksums for swaggo/swag and go-openapi packages |
| docs/swagger.yaml | Generated OpenAPI 2.0 specification in YAML format |
| docs/swagger.json | Generated OpenAPI 2.0 specification in JSON format |
| docs/docs.go | Generated Go code registering Swagger documentation |
| beacon-chain/rpc/prysm/doc.go | Package-level Swagger metadata (title, version, contact, license) |
| beacon-chain/rpc/prysm/beacon/handlers.go | Swagger annotations for GetWeakSubjectivity, GetIndividualVotes, GetChainHead, PublishBlobs endpoints |
| beacon-chain/rpc/prysm/beacon/ssz_query.go | Swagger annotations for QueryBeaconState and QueryBeaconBlock endpoints |
| beacon-chain/rpc/prysm/beacon/validator_count.go | Swagger annotations for GetValidatorCount endpoint (dual-path /prysm and /eth) |
| beacon-chain/rpc/prysm/node/handlers.go | Swagger annotations for ListTrustedPeer, AddTrustedPeer, RemoveTrustedPeer endpoints |
| beacon-chain/rpc/prysm/validator/handlers.go | Swagger annotations for GetParticipation and GetActiveSetChanges endpoints |
| beacon-chain/rpc/prysm/validator/validator_performance.go | Swagger annotations for GetPerformance endpoint |
| changelog/willianpaixao_swagger.md | Changelog entry documenting the feature addition |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
To run swagger-ui with Docker, simply run the following command from the project root folder: $ docker run --rm --publish 8080:8080 --env SWAGGER_JSON=/docs/swagger.json --volume ./docs:/docs docker.swagger.io/swaggerapi/swagger-uiFollow some screenshots: 
|
Signed-off-by: Willian Paixao <[email protected]>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 13 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
2 participants
What type of PR is this?
Feature
What does this PR do? Why is it needed?
This PR adds Swagger 2.0 documentation for all Prysm API endpoints (14 routes total). Custom Prysm endpoints (/prysm/node/, /prysm/v1/validators/, /prysm/v1/beacon/*) were previously undocumented, making them difficult for developers to discover and use.
This implements annotation-based documentation using swaggo/swag, generating machine-readable API specification files (swagger.yaml, swagger.json) that can be used for client SDK generation, API exploration, and interactive documentation.
Technical Details
Swagger Generation:
Implementation Notes:
@Routerannotations for GetValidatorCount (accessible at both/prysm/v1and/eth/v1paths)Which issues(s) does this PR fix?
Fixes #12794
Changelog Entry
A changelog fragment file will be added for this user-facing feature addition per CONTRIBUTING.md requirements.
Future Enhancements
This PR provides the foundation for:
/swagger/index.html(requires adding http-swagger dependency)Acknowledgements