S8n.MySolutionTemplate/plans/scalar-httprequest-playground.md

# Implementation Plan: Replace Swagger with Scalar, Add HttpRequest Component, Create PlaygroundPage

## Overview
This plan outlines the steps to accomplish three main tasks:
1. Replace the current OpenAPI UI (Swagger) with Scalar API reference UI in the backend.
2. Add a new HttpRequest component (similar to Calculator) for making HTTP requests.
3. Create a PlaygroundPage.vue for dynamic s8n components manipulation.

## Task 1: Replace Swagger with Scalar

### Current State
- Backend uses `Microsoft.AspNetCore.OpenApi` package (built-in OpenAPI).
- OpenAPI endpoint is mapped via `app.MapOpenApi()` in development environment.
- No Swashbuckle/Swagger UI currently installed.

### Requirements
- Integrate Scalar as middleware to serve a modern API reference UI.
- Maintain OpenAPI specification generation (already provided by `AddOpenApi`).
- Scalar UI should be accessible at a dedicated route (e.g., `/scalar`).

### Implementation Steps

#### 1.1 Add Scalar.AspNetCore NuGet Package
Add package reference to `MyCompany.MyProject.BackendApi.csproj`:
```xml
<PackageReference Include="Scalar.AspNetCore" Version="2.0.0" />
```

#### 1.2 Configure Scalar Middleware
Modify `Program.cs`:
- Keep `builder.Services.AddOpenApi()` for OpenAPI spec generation.
- Replace `app.MapOpenApi()` with Scalar middleware in development environment.
- Configure Scalar to use the generated OpenAPI spec.

Example code:
```csharp
if (app.Environment.IsDevelopment())
{
    app.MapScalarApiReference();
    // Optional: keep MapOpenApi if needed for raw spec
    app.MapOpenApi();
}
```

#### 1.3 Customize Scalar Settings (Optional)
Configure Scalar options (title, theme, etc.) via `AddScalar`.

### Expected Outcome
- Visiting `/scalar` in browser displays Scalar API reference UI.
- OpenAPI spec remains available at `/openapi/v1.json`.

## Task 2: Add HttpRequest Component

### Component Structure

#### 2.1 C# Backend Component
- **Location**: `S8n.Components.Packages/Basics/HttpRequest.cs`
- **Namespace**: `S8n.Components.Basics`
- **Class**: `HttpRequest`
- **Method**: `Execute` (or `Request`)
- **Inputs**:
  - `method` (string): HTTP method (GET, POST, PUT, DELETE, etc.)
  - `url` (string): Target URL
  - `headers` (Dictionary<string, string>): Optional request headers
  - `body` (object): Optional request body (serialized as JSON)
- **Outputs**:
  - `statusCode` (int): HTTP status code
  - `response` (string): Response body as string
  - `headers` (Dictionary<string, string>): Response headers
  - `duration` (long): Request duration in milliseconds

Implementation will use `HttpClient` to make the request.

#### 2.2 Vue Frontend Component
- **Location**: `QuasarFrontend/src/components_s8n/ComponentHttpRequest.vue`
- **Pattern**: Follow `ComponentCalculator.vue` structure.
- **UI Elements**:
  - Dropdown for HTTP method (GET, POST, PUT, DELETE, etc.)
  - Text input for URL
  - Dynamic key-value pair inputs for headers (add/remove)
  - JSON editor for request body (textarea with JSON validation)
  - Execute button with loading state
  - Display response status, headers, body, and duration

#### 2.3 Component Definition Markdown
- **Location**: `components/basics/httprequest.md`
- **Format**: Similar to `calculator.md` with appropriate inputs/outputs.

### Implementation Steps

#### 2.4 Create C# Class
1. Create `HttpRequest.cs` file.
2. Implement method with error handling (timeout, invalid URL, etc.).
3. Ensure JSON serialization/deserialization.

#### 2.5 Create Vue Component
1. Create `ComponentHttpRequest.vue`.
2. Use `runtime.createExecutor` with appropriate types.
3. Design UI using Quasar components.

#### 2.6 Create Markdown Definition
1. Create `httprequest.md` with YAML definition.

#### 2.7 Register Component (if needed)
- The runtime automatically discovers classes via reflection; no explicit registration required.

## Task 3: Create PlaygroundPage.vue

### Requirements
- A dedicated page for interacting with s8n components.
- Dynamic component selection and rendering.
- Support for multiple components (Calculator, HttpRequest, future components).

### Implementation Steps

#### 3.1 Add Route
Modify `QuasarFrontend/src/router/routes.ts`:
```typescript
{
  path: '/playground',
  component: () => import('layouts/MainLayout.vue'),
  children: [{ path: '', component: () => import('pages/PlaygroundPage.vue') }],
}
```

#### 3.2 Create PlaygroundPage.vue
- **Location**: `QuasarFrontend/src/pages/PlaygroundPage.vue`
- **Structure**:
  - Left sidebar: List of available components (hardcoded for now).
  - Main content: Dynamic component render area.
  - Output display area (could be integrated into each component).

#### 3.3 Component Registry
Create a component registry file (`src/components_s8n/registry.ts`) that exports:
- Component definitions (name, description, Vue component import).
- Dynamic import of components.

#### 3.4 Dynamic Component Loading
Use Vue's `<component :is="selectedComponent">` to render selected component.

#### 3.5 UI Enhancements
- Use Quasar's `q-select` for component selection.
- Provide a clean layout with card containers.

## Dependencies and Considerations

### Backend Dependencies
- `Scalar.AspNetCore` (new)
- `Microsoft.AspNetCore.OpenApi` (already present)
- `System.Net.Http` (for HttpRequest component)

### Frontend Dependencies
- None new; use existing Quasar and Vue.

### Testing
- Test Scalar UI loads correctly.
- Test HttpRequest component with mock HTTP server.
- Test PlaygroundPage navigation and component switching.

## Timeline and Priority
1. **Priority 1**: HttpRequest component (core functionality).
2. **Priority 2**: PlaygroundPage (user interface).
3. **Priority 3**: Scalar integration (documentation).

## Success Criteria
- Scalar UI accessible at `/scalar` (development only).
- HttpRequest component works for basic GET/POST requests.
- PlaygroundPage renders Calculator and HttpRequest components.
- No regression in existing Calculator component.

## Notes
- Scalar integration may require configuration for production; currently planned for development only.
- HttpRequest component should handle CORS limitations (backend acts as proxy).
- PlaygroundPage can be extended later with component discovery from backend API.

## Next Steps
1. Review this plan with stakeholders.
2. Proceed to implementation in Code mode.