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:

<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:

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:

{
  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.