diff --git a/markdown/docs/tools/studio/_section.md b/markdown/docs/tools/studio/_section.md new file mode 100644 index 000000000000..1f4d7d5d1e02 --- /dev/null +++ b/markdown/docs/tools/studio/_section.md @@ -0,0 +1,4 @@ +--- +title: Studio +weight: 20 +--- \ No newline at end of file diff --git a/markdown/docs/tools/studio/architecture.md b/markdown/docs/tools/studio/architecture.md new file mode 100644 index 000000000000..185c37564cbd --- /dev/null +++ b/markdown/docs/tools/studio/architecture.md @@ -0,0 +1,246 @@ +--- +title: 'Architecture' +weight: 50 +--- + +AsyncAPI Studio is built as a monorepo using Turbo, with a modular architecture that separates concerns into distinct services and components. The application follows a layered architecture pattern: + +```mermaid +graph TD + classDef layer fill:#e1f5fe,stroke:#01579b,stroke-width:2px + classDef component fill:#fff,stroke:#01579b,stroke-width:1px + + UI[User Interface Layer]:::layer + SL[Services Layer]:::layer + CL[Core Libraries Layer]:::layer + ED[External Dependencies]:::layer + + UI --> SL + SL --> CL + CL --> ED +``` + +### Layer Breakdown + +```mermaid +graph TD + classDef layer fill:#e1f5fe,stroke:#01579b,stroke-width:2px + classDef component fill:#fff,stroke:#01579b,stroke-width:1px + + subgraph UI[User Interface Layer] + direction LR + UI_C[UI Components]:::component + Nav[Navigation]:::component + Ed[Editor]:::component + Vis[Visualization]:::component + end + + subgraph SL[Services Layer] + direction LR + ES[Editor Service]:::component + PS[Parser Service]:::component + NS[Navigation Service]:::component + SM[State Management]:::component + end + + subgraph CL[Core Libraries Layer] + direction LR + AP[AsyncAPI Parser]:::component + AR[AsyncAPI React]:::component + ME[Monaco Editor]:::component + RF[React Flow]:::component + end +``` + +## Key Components + +AsyncAPI Studio consists of several key components that work together to provide a seamless experience: + +### User Interface Components + +The UI layer consists of React components organized into logical groups: + +1. **Core Components**: Base UI components like buttons, inputs, panels, and modals +2. **Navigation Components**: Sidebar, tabs, and navigation controls +3. **Editor Components**: Monaco editor integration and editor-related UI +4. **Visualization Components**: React Flow integration for API visualization +5. **Preview Components**: Documentation preview using AsyncAPI React component + +### Services Layer + +The services layer provides the core functionality of the application: + +#### Editor Service + +The Editor Service handles all aspects of editing AsyncAPI documents: + +- Manages Monaco Editor configuration and integration +- Provides syntax highlighting and code completion +- Handles file loading and saving +- Manages document format conversion (YAML/JSON) + +#### Parser Service + +The Parser Service is responsible for processing and validating AsyncAPI documents: + +- Integrates with the AsyncAPI Parser library +- Validates documents against the AsyncAPI schema +- Processes validation results and error reporting +- Handles schema resolution and references + +#### Navigation Service + +The Navigation Service manages navigation within the application: + +- Controls switching between different views (Editor, Preview, Visualize) +- Manages the sidebar navigation +- Handles URL routing and state persistence +- Coordinates interactions between different views + +### State Management + +AsyncAPI Studio uses Zustand for state management, with several stores: + +1. **Editor Store**: Manages the editor state, content, and configuration +2. **Parser Store**: Stores validation results and parsed document information +3. **UI Store**: Manages UI state like sidebar visibility and active panels +4. **Settings Store**: Handles user preferences and application settings + +## Technology Stack + +AsyncAPI Studio is built using modern web technologies: + +### Frontend Technologies + +- **React**: For building the user interface +- **Next.js**: For server-side rendering and routing +- **TailwindCSS**: For styling and design system +- **Monaco Editor**: For the code editing experience +- **React Flow**: For interactive API visualizations +- **Zustand**: For state management + +### AsyncAPI Technologies + +- **AsyncAPI Parser**: For validating and processing AsyncAPI documents +- **AsyncAPI Converter**: For converting between different AsyncAPI versions +- **AsyncAPI React**: For rendering documentation previews +- **AsyncAPI Generator**: For code generation from specifications + +### Build and Development Tools + +- **Turbo**: For monorepo management and efficient builds +- **pnpm**: For package management +- **TypeScript**: For type-safe code +- **ESLint/Prettier**: For code quality and formatting +- **Jest/React Testing Library**: For testing + +## Data Flow + +The following diagram illustrates how data flows through the application: + +```mermaid +sequenceDiagram + participant User + participant UI as User Interface + participant ES as Editor Service + participant PS as Parser Service + participant NS as Navigation Service + participant API as External APIs + + User->>UI: Edit document + UI->>ES: Update document content + ES->>PS: Request validation + PS->>PS: Validate document + PS->>UI: Return validation results + + User->>UI: Request preview + UI->>NS: Navigate to preview + NS->>PS: Get parsed document + PS->>UI: Return parsed document + UI->>UI: Render preview + + User->>UI: Generate code + UI->>API: Send document for generation + API->>UI: Return generated code + UI->>User: Download code +``` + +## Deployment + +AsyncAPI Studio supports multiple deployment models: + +### Hosted Version +The hosted version at [studio.asyncapi.com](https://studio.asyncapi.com) is deployed as a static site on cloud infrastructure: +```mermaid +graph LR + classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px + classDef service fill:#fff,stroke:#01579b,stroke-width:1px + + U[User]:::user + CDN[CDN]:::service + SW[Static Website]:::service + AS[API Services]:::service + CG[Code Generation]:::service + DS[Document Storage]:::service + + U --> CDN + CDN --> SW + U --> AS + AS --> CG + AS --> DS + + style U fill:#e1f5fe,stroke:#01579b,stroke-width:2px + style CDN fill:#fff,stroke:#01579b,stroke-width:1px + style SW fill:#fff,stroke:#01579b,stroke-width:1px + style AS fill:#fff,stroke:#01579b,stroke-width:1px + style CG fill:#fff,stroke:#01579b,stroke-width:1px + style DS fill:#fff,stroke:#01579b,stroke-width:1px +``` + +### Local Deployment + +When deployed locally, AsyncAPI Studio runs as a standalone application: + +```mermaid +graph LR + classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px + classDef service fill:#fff,stroke:#01579b,stroke-width:1px + + U[User]:::user + B[Browser]:::service + N[Next.js Server]:::service + FS[File System]:::service + + U --> B + B --> N + N --> FS +``` + +### Docker Deployment + +The Docker deployment packages the application in a lightweight container: + +```mermaid +graph LR + classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px + classDef service fill:#fff,stroke:#01579b,stroke-width:1px + + U[User]:::user + B[Browser]:::service + N[Nginx Server]:::service + SF[Static Files]:::service + + U --> B + B --> N + N --> SF +``` + +## Design Decisions + +Several key design decisions that shape AsyncAPI Studio's architecture: + +1. **Monorepo Structure**: Allows sharing code between applications while maintaining separation +2. **Service-Based Architecture**: Separates concerns into distinct services +3. **Local-First Processing**: Performs validation and parsing client-side for better performance +4. **Extensible Plugin System**: Enables future extensions through plugins +5. **Responsive Design**: Works on various devices and screen sizes diff --git a/markdown/docs/tools/studio/index.md b/markdown/docs/tools/studio/index.md new file mode 100644 index 000000000000..a2d2eebd1f46 --- /dev/null +++ b/markdown/docs/tools/studio/index.md @@ -0,0 +1,51 @@ +--- +title: 'Introduction' +weight: 20 +--- + +AsyncAPI Studio is a web-based tool designed specifically for working with AsyncAPI specifications. It provides an integrated environment for developing, validating, converting, and visualizing AsyncAPI documents, making it easier to create and manage your asynchronous API definitions. + +## Key Features + +AsyncAPI Studio offers a rich set of features to streamline your AsyncAPI development workflow: + +* **Advanced Editor**: Build and edit AsyncAPI documents with syntax highlighting, code completion, and error detection +* **Validation**: Instantly validate your AsyncAPI documents against schema rules +* **Version Conversion**: Convert specifications between different AsyncAPI versions +* **Documentation Preview**: Render beautiful documentation using the AsyncAPI React component +* **Visual Flow Diagrams**: Visualize message flows between systems for better understanding +* **Code Generation**: Generate code from your AsyncAPI specifications using various templates +* **Collaboration**: Share your AsyncAPI documents with others through URLs or file exports + +## Why Use AsyncAPI Studio? + +AsyncAPI Studio simplifies the process of working with AsyncAPI specifications by providing all the tools you need in one place: + +* **User-Friendly Interface**: Designed for both beginners and experienced AsyncAPI users +* **Immediate Feedback**: Get instant validation as you type to catch errors early +* **Visualization**: See your API structure visually to better understand message flows +* **No Installation Required**: Use the online version at [studio.asyncapi.com](https://studio.asyncapi.com) or deploy locally + +## Studio Architecture + +AsyncAPI Studio is built with modern web technologies: + +```mermaid +graph TD; + A[User Interface] --> B[Editor Service] + A --> C[Parser Service] + A --> D[Navigation Service] + B --> E[Monaco Editor] + C --> F[AsyncAPI Parser] + D --> G[Code Generation] + D --> H[HTML Preview] + D --> I[Block Visualizer] +``` + +The application integrates several key components: +* **Monaco Editor**: Powers the advanced code editing capabilities +* **AsyncAPI Parser**: Validates and processes specifications +* **React Flow**: Creates interactive visualizations of your API components +* **AsyncAPI React**: Renders beautiful documentation previews + +Whether you're just getting started with AsyncAPI or you're an experienced user, AsyncAPI Studio provides the tools you need to create high-quality AsyncAPI specifications efficiently. \ No newline at end of file diff --git a/markdown/docs/tools/studio/installation.md b/markdown/docs/tools/studio/installation.md new file mode 100644 index 000000000000..2c0dbfc92ac3 --- /dev/null +++ b/markdown/docs/tools/studio/installation.md @@ -0,0 +1,144 @@ +--- +title: 'Installation Guide' +weight: 30 +--- + +AsyncAPI Studio is available both as an online service and as a local application that you can run on your own machine. This guide will walk you through the different installation and deployment options. + +## Online Service + +The easiest way to use AsyncAPI Studio is through the hosted online version at: + +[https://studio.asyncapi.com](https://studio.asyncapi.com) + +This version requires no installation and provides all the features of AsyncAPI Studio directly in your browser. + +## Local Installation + +You can also run AsyncAPI Studio locally using one of the following methods: + +### Using Node.js + +Prerequisites: +- [Node.js](https://nodejs.org/) v18 or higher +- [pnpm](https://pnpm.io/installation) (preferred) or npm + +1. Clone the repository: + ```sh + git clone https://github.com/asyncapi/studio.git + cd studio + ``` + +2. Install dependencies: + ```sh + pnpm install + ``` + +3. Start the development server: + ```sh + pnpm run studio + ``` + +4. Open your browser and navigate to: + ``` + http://localhost:3000 + ``` + +### Using Docker + +If you prefer to use Docker, AsyncAPI Studio provides a Docker image that you can easily run: + +1. Pull the latest Docker image: + ```sh + docker pull asyncapi/studio:latest + ``` + +2. Run the container: + ```sh + docker run -p 80:80 asyncapi/studio + ``` + +3. Open your browser and navigate to: + ``` + http://localhost + ``` + +Alternatively, you can build the Docker image yourself: + +```sh +git clone https://github.com/asyncapi/studio.git +cd studio +docker build -f apps/studio/Dockerfile -t asyncapi/studio . +docker run -p 80:80 asyncapi/studio +``` + +#### Docker Compose Example + +For more complex deployments, you can use Docker Compose. Create a file named `docker-compose.yml` with the following content: + +```yaml +version: '3' +services: + studio: + image: asyncapi/studio:latest + ports: + - "8080:80" + restart: unless-stopped + environment: + - NEXT_PUBLIC_GA_TRACKING_ID=your-ga-id +``` + +Then run: + +```sh +docker-compose up -d +``` +This will start AsyncAPI Studio in detached mode, making it accessible at http://localhost:8080. + +Use `docker logs` to troubleshoot issues + +### Using the AsyncAPI CLI + +You can also start AsyncAPI Studio locally using the [AsyncAPI CLI](../cli/): + +1. Install the AsyncAPI CLI globally: + ```sh + npm install -g @asyncapi/cli + ``` + +2. Use the `start studio` command: + ```sh + asyncapi start studio + ``` + +3. A browser window should automatically open with AsyncAPI Studio running locally. + +## Production Build + +If you want to build AsyncAPI Studio for production deployment: + +1. Clone the repository: + ```sh + git clone https://github.com/asyncapi/studio.git + cd studio + ``` + +2. Install dependencies: + ```sh + pnpm install + ``` + +3. Build for production: + ```sh + pnpm run build:studio + ``` + +The build artifacts will be stored in the `apps/studio/.next` directory and can be served using any static file server or deployment platform. + +## System Requirements + +- **Browser**: Latest versions of Chrome, Firefox, Safari, or Edge +- **For local development**: + - Minimum 2GB RAM + - 1GB of free disk space + - Node.js v18 or higher \ No newline at end of file diff --git a/markdown/docs/tools/studio/usage.md b/markdown/docs/tools/studio/usage.md new file mode 100644 index 000000000000..9f7dab2ccaff --- /dev/null +++ b/markdown/docs/tools/studio/usage.md @@ -0,0 +1,150 @@ +--- +title: 'Usage' +weight: 40 +--- + +When you first open AsyncAPI Studio, you'll see the main editor interface with the following components: + +1. **Editor Panel**: The central area where you write and edit your AsyncAPI document +2. **Navigation Sidebar**: Access different views and tools +3. **Preview Panel**: View documentation, visual diagrams, or generated code +4. **Toolbar**: Access common actions like validation, saving, and sharing + +## Creating a New AsyncAPI Document + +To create a new AsyncAPI document: + +1. Click on the **New Document** button in the toolbar +2. Select the AsyncAPI version you want to use (2.0.0, 2.1.0, 2.2.0, etc.) +3. Choose a template to start with (Minimal, Kafka, MQTT, etc.) or start from scratch +4. Begin editing your document in the editor panel + +## Editing AsyncAPI Documents + +The Studio editor provides several features to help you create and edit AsyncAPI documents: + +### Syntax Highlighting + +The editor automatically highlights different parts of your AsyncAPI document to make it easier to read and understand: + +- Keywords and property names +- Values and types +- References and components +- Comments and annotations + +### Code Completion + +As you type, the editor suggests completions based on the AsyncAPI specification: + +1. Press **Ctrl+Space** (or **Cmd+Space** on Mac) to manually trigger suggestions +2. The editor will suggest property names, values, and schema components based on the context + +### Error Detection + +The editor validates your document in real-time and highlights errors: + +- Syntax errors are marked with red squiggly underlines +- Hover over an error to see a description of the problem +- The status bar at the bottom shows the total number of errors and warnings + +## Validating Your AsyncAPI Document + +To validate your AsyncAPI document and see detailed validation results: + +1. Click the **Validate** button in the toolbar +2. The validation panel will appear showing any errors or warnings +3. Click on an error to jump to its location in the document +4. Fix the issues and re-validate until all errors are resolved + +## Converting Between AsyncAPI Versions + +To convert your AsyncAPI document to a different version: + +1. Click on the **Convert** button in the toolbar +2. Select the target version you want to convert to +3. Review the converted document in the preview panel +4. Click **Apply** to replace your document with the converted version, or **Cancel** to discard + +## Previewing Documentation + +To see how your AsyncAPI document will be rendered as documentation: + +1. Click on the **Preview** tab in the preview panel +2. The documentation will be rendered using the AsyncAPI React component +3. Scroll through the preview to see all sections of your document +4. The preview updates automatically as you edit your document + +## Visualizing Your API + +To visualize the structure and message flows of your API: + +1. Click on the **Visualize** tab in the preview panel +2. The visualization will show: + - Services and operations + - Message flows between components + - Message schemas and formats +3. You can: + - Zoom in/out using the mouse wheel + - Drag components to rearrange the diagram + - Click on components to see their details + +## Generating Code + +To generate code from your AsyncAPI document: + +1. Click on the **Generate** tab in the preview panel +2. Select a template from the dropdown menu +3. Configure any template-specific options +4. Click **Generate** to create the code +5. Download the generated code as a ZIP file + +## Sharing Your AsyncAPI Document + +You can share your AsyncAPI document in several ways: + +### URL Sharing + +1. Click on the **Share** button in the toolbar +2. Copy the provided URL +3. Share the URL with others who can view and edit your document + +### File Export + +1. Click on the **Download** button in the toolbar +2. Select the format you want to export to (YAML or JSON) +3. Save the file to your computer or share it directly + +## Keyboard Shortcuts + +AsyncAPI Studio provides several keyboard shortcuts to improve productivity: + +| Action | Windows/Linux | macOS | +|--------|--------------|-------| +| Save | Ctrl+S | Cmd+S | +| Find | Ctrl+F | Cmd+F | +| Replace | Ctrl+H | Cmd+H | +| Format Document | Shift+Alt+F | Shift+Option+F | +| Validate | Ctrl+Shift+V | Cmd+Shift+V | +| Toggle Comment | Ctrl+/ | Cmd+/ | +| Indent | Tab | Tab | +| Outdent | Shift+Tab | Shift+Tab | + +## Best Practices + +Here are some tips for effectively using AsyncAPI Studio: + +1. **Start with a template**: Use the provided templates as a starting point to save time +2. **Validate regularly**: Validate your document frequently to catch errors early +3. **Use components**: Define reusable schemas in the components section for better organization +4. **Add descriptions**: Include detailed descriptions for operations, messages, and schemas +5. **Use examples**: Provide examples for messages to help users understand the API better +6. **Organize your document**: Use meaningful operation IDs and message names for clarity + +## Troubleshooting + +If you encounter issues while using AsyncAPI Studio: + +1. **Editor not loading**: Try clearing your browser cache and reloading the page +2. **Validation errors**: Check the AsyncAPI specification version you're using and ensure your document follows that version +3. **Preview not updating**: Save your document and refresh the preview panel +4. **Performance issues**: For large documents, consider splitting them into smaller files and using references \ No newline at end of file