feat: add automatic Merkle API documentation generation #412
Conversation
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
Implements automatic documentation generation for the Merkle API using OpenAPI/Swagger specification, resolving issue sablier-labs#335. ## Changes - Created OpenAPI specification (`specs/merkle-api.yaml`) for all 3 Merkle API endpoints: - POST /api/create - Create Merkle airdrop campaigns - GET /api/eligibility - Check recipient eligibility - GET /api/validity - Validate campaign IPFS CID - Added CLI command (`cli/commands/autogen/merkle.ts`) for auto-generating docs - Integrated into main autogen workflow - Follows same pattern as existing GraphQL autogen - Configured Docusaurus with OpenAPI plugin: - Installed docusaurus-plugin-openapi-docs and docusaurus-theme-openapi-docs - Added plugin configuration to config/plugins.ts - Added theme to docusaurus.config.ts - Set docItemComponent to @theme/ApiItem for proper SSG support - Auto-generated documentation files: - API overview page - Individual endpoint pages with request/response schemas - Tag pages for API organization ## Benefits - Single source of truth for API documentation (the OpenAPI spec) - Automatic regeneration on build via autogen command - Consistent, professional formatting - Interactive API explorer (Swagger UI) - Reduced manual maintenance burden ## Related Issues - Closes sablier-labs#335 - Related: sablier-labs/merkle-api#47 (future full automation from Rust code)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
Implements automatic documentation generation for the Merkle API using OpenAPI/Swagger specification.
Resolves #335
Changes
1. OpenAPI Specification
specs/merkle-api.yamlwith complete API documentation for:POST /api/create- Create Merkle airdrop campaignsGET /api/eligibility- Check recipient eligibilityGET /api/validity- Validate campaign IPFS CID2. Auto-Generation CLI Command
cli/commands/autogen/merkle.tsfor generating docs from spec3. Docusaurus Configuration
docusaurus-plugin-openapi-docsanddocusaurus-theme-openapi-docsdocItemComponent: "@theme/ApiItem"for proper SSG support4. Auto-Generated Documentation
Benefits
bun run cli/index.ts autogenTesting
Build tested successfully:
Related Issues
Future Work
The OpenAPI spec is currently maintained manually in this repo. For 100% automation, see merkle-api#47 which proposes adding
utoipato the Rust backend to auto-generate the spec from code.