feat(asyncapi): add AsyncAPI plugin for event-driven API documentation#1950
Open
picsoung wants to merge 12 commits intozuplo:mainfrom
Open
feat(asyncapi): add AsyncAPI plugin for event-driven API documentation#1950picsoung wants to merge 12 commits intozuplo:mainfrom
picsoung wants to merge 12 commits intozuplo:mainfrom
Conversation
|
@picsoung is attempting to deploy a commit to the Zuplo Team on Vercel. A member of the Team first needs to authorize it. |
|
Preview build of published Zudoku package Warning This PR is from an external contributor. To run the public package build workflow, a maintainer must add the |
Implements AsyncAPI 3.0 plugin foundation following OpenAPI patterns: Core Infrastructure: - AsyncAPI 3.0 TypeScript types (AsyncAPIDocument, ChannelObject, etc.) - GraphQL schema with Pothos builder (Schema, Channel, Operation, Message) - Parser with validation and dereferencing support - Protocol detection from bindings and servers - Operation enrichment with channel addresses Plugin System: - Plugin factory function (asyncApiPlugin) - GraphQL client infrastructure - React context providers - Configuration interfaces with versioning support Tests: - Plugin creation tests (5 tests) - Parser validation tests (5 tests) - All 10 tests passing ✅ Dependencies: - Added @asyncapi/parser@^3.0.0 Package exports updated for asyncapi plugin. Phase 1 Complete - Ready for Phase 2 (Parser & Validation) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Implements comprehensive parsing and validation utilities: Parser Utilities: - Protocol detection from bindings, servers, and URLs - Operation extraction and enrichment with protocols - Filtering by action, tag, protocol - Grouping operations by tag and channel - Support for all major protocols (WebSocket, MQTT, Kafka, AMQP, etc.) Processor Functions: - removeChannels - Filter channels from AsyncAPI docs - removeOperations - Filter operations by criteria - removeExtensions - Remove x- extensions - traverse utility for schema processing Tests: - Protocol detection (24 tests) - Operations extraction (23 tests) - Processor functions (23 tests) - All 80 tests passing ✅ Phase 2 Complete - Ready for Phase 3 (UI Components) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add isDereferencedChannel helper to detect resolved $ref values - Update extractOperations to handle three channel reference formats: 1. Already dereferenced (channel is the actual object) 2. Direct string reference 3. Object with $ref property - Add integration tests with sample AsyncAPI documents - Add debug test for inspecting parsed document structure - Create sample documents (asyncapi.json, asyncapi-simple.json) for testing Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
UI Components: - ProtocolBadge: colored badges for WebSocket, MQTT, Kafka, etc. - OperationBadge: SEND/RECEIVE action badges - MessageView: displays message schemas with payload and headers - OperationListItem: single operation display with protocol info - OperationList: list of operations by tag with pagination Routing & Navigation: - getRoutes: creates React Router routes for operations - AsyncApiProvider: context wrapper with GraphQL client - createNavigationCategory: builds navigation structure Infrastructure: - GraphQL queries for fetching schemas and operations - useCreateQuery hook for React Query integration - Protocol and action color mappings All 100 tests pass with no type errors. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ssing Implements Vite plugin infrastructure for AsyncAPI following the OpenAPI pattern: - Add AsyncApiSchemaManager for build-time schema processing and file tracking - Add schema-codegen for generating JS with resolved $ref references - Add plugin-asyncapi Vite plugin with virtual module support - Add asyncApis config schema (url/file/raw types) - Fix GraphQL server to handle schemaImports from Vite plugin - Fix tag matching for null slug (untagged operations) - Add example config using file-based asyncApis This fixes hydration errors with large AsyncAPI specs by processing schemas at build time instead of runtime. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Normalize protocols (ws/wss -> ws) to prevent duplicate WebSocket badges - Add oneOf/anyOf schema support in PayloadSchemaView component - Display each message type option with title and description - Support nested object rendering and enum/const display - Improve payload schema rendering with proper type annotations Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix tag inheritance from channels to operations in getAllOperations - Fix slug resolution in GraphQL OperationItem resolver to look up from context - Fix navigation category to use proper slug fallback - Fix redirect logic to find first named tag - Update MessageView and ChannelView components to use GraphQL result types - Add proper null checks for unknown types in ChannelView Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add new ChannelGroup component to display operations grouped by channel - Show Publish (send) and Subscribe (receive) sections within each channel - Update OperationList to use channel grouping instead of individual operations - Update navigation to link to channels instead of individual operations - Include connection info sidecar with protocol, channel, and action details - Support message examples with auto-generation from schema Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Change action labels from Publish/Subscribe to Send/Receive - Use channel title instead of channel address in navigation menu - Add channelTitle field to GraphQL operations and queries - Display channel title as heading when available Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Make action labels dynamic by capitalizing the operation action value - Remove hardcoded "Send" and "Receive" labels - Remove channel description display from the UI - Refactor ChannelSidecar to accept operations array instead of sendOp/receiveOp - Add helper functions for action icons and colors Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Refactor ChannelGroup to use Frame, FramePanel, Item components - Add collapsible Send/Receive operation sections with chevron icons - Use SchemaView from OpenAPI for displaying message payload schemas - Add MessagesSidecar organized by action (send/receive) with icons - Show message descriptions in header only (not duplicated in schema box) - Add ParamInfos for inline type display - Use RadixCollapsible for proper layout control on expanded schemas Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds support for displaying multiple protocols (WebSocket, MQTT, Kafka, AMQP, etc.) with dedicated components for channel parameters, headers, and security display. Refactors UI to align with OpenAPI component patterns for consistency. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
picsoung
force-pushed
the
async-plugin
branch
from
58c3e19 to
8d68c3d
Compare
|
Great work on the AsyncAPI plugin! The multi-protocol support (WebSocket, MQTT, Kafka, AMQP) is impressive. One thing I've seen in production with event-driven APIs: the gap between documented behavior and actual runtime behavior tends to be much wider than with REST APIs. A documented Kafka topic might have messages arriving out of order, or a WebSocket endpoint might silently drop connections under load -- things that are hard to catch in documentation alone. Have you considered adding optional runtime health indicators alongside the documentation? For example:
This would make Zudoku not just a docs viewer but a real-time API observatory. Just a thought -- the plugin architecture you've set up with the separate |
Contributor
Author
|
@desiorac that's a good suggestion, but what you describe sounds like dynamic data, that would need to be fetched from the gateway or an observability tool like Datadog. Maybe it's easier to have a dedicated "status" or "health" page instead of cramping the doc. |
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
2 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.
Summary
This PR introduces a complete AsyncAPI plugin for Zudoku, enabling documentation of event-driven APIs alongside REST APIs.
Key Features
Test plan
nx run asyncapi-sample:devand verify the multi-protocol example renderspnpm checkto verify linting passes🤖 Generated with Claude Code