@flink-app/api-docs-plugin 0.12.1-alpha.9 → 0.13.1

package/BUILD.md

@@ -0,0 +1,52 @@
+# Build Process for API Docs Plugin
+
+This plugin consists of two main parts:
+1. The TypeScript plugin code
+2. A React application for the documentation UI
+
+## Directory Structure
+
+```
+api-docs-plugin/
+├── src/                    # TypeScript plugin source
+├── react-app/              # React application source
+│   ├── src/                # React components
+│   └── dist/               # Built React files (after build)
+└── dist/                   # Compiled plugin output
+    ├── index.js            # Compiled plugin
+    └── react-app/          # Copied React build files
+```
+
+## Build Process
+
+The build process follows these steps:
+
+1. **Build React App**: 
+   - Runs `npm run build` in the `react-app` directory
+   - Outputs files to `react-app/dist`
+
+2. **Compile TypeScript**:
+   - Compiles all TypeScript files from `src/` to `dist/`
+
+3. **Copy Assets**:
+   - Copies the built React app from `react-app/dist` to `dist/react-app`
+
+## Commands
+
+- `npm run prepare`: Runs the full build process (React + TypeScript + copy)
+- `npm run build:react`: Builds only the React app
+- `npm run clean`: Removes the dist directory
+
+## How It Works
+
+1. The plugin serves the React app from `dist/react-app` at the `/docs` endpoint
+2. The React app fetches API data from `/docs/api`
+3. The plugin provides the API data based on registered Flink handlers
+
+## Development
+
+For development, you can run:
+- `npm run dev`: Starts a development server
+- `npm run watch`: Watches for TypeScript changes
+
+Make sure to build the React app before testing the full plugin.

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @flink-app/api-docs-plugin
+
+## 0.13.1
+
+### Patch Changes
+
+-   Fixed invalid types and improve typescript error message during schema compilation
+
+## 0.13.0
+
+### Minor Changes
+
+-   Migrate to pnpm and streamlines build process.

package/DEVELOPMENT.md

@@ -0,0 +1,64 @@
+# Development Guide for API Docs Plugin
+
+This guide explains how to develop the API Docs Plugin React app.
+
+## Prerequisites
+
+- Node.js installed (see root .nvmrc for version)
+- Dependencies installed in both the plugin root and react-app directories:
+  ```bash
+  npm install
+  cd react-app && npm install
+  ```
+
+## Development Setup
+
+The development setup consists of two servers:
+
+1. **Mock API Server** (port 3001): Serves sample API data
+2. **Vite Dev Server** (port 5173): Serves the React app with hot-reloading
+
+## Running the Development Environment
+
+1. Start the mock API server:
+   ```bash
+   npm run dev:mock-api
+   ```
+
+2. In another terminal, start the React dev server:
+   ```bash
+   npm run dev:react
+   ```
+
+3. Open http://localhost:5173 in your browser
+
+The React app will fetch data from the mock API server through Vite's proxy configuration.
+
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev:mock-api` | Start the mock API server |
+| `npm run dev:react` | Start the React development server |
+| `npm run build:react` | Build the React app for production |
+| `npm run prepare` | Build everything for production |
+| `npm run clean` | Remove all build artifacts |
+
+## Modifying Sample Data
+
+To test different API structures, edit `sample.json` and restart the mock API server.
+
+## Building for Production
+
+To build the complete plugin:
+
+```bash
+npm run prepare
+```
+
+This will:
+1. Build the React app
+2. Compile TypeScript
+3. Copy assets to the dist directory
+
+The built plugin will serve the React app statically in production.

package/dist/dev-server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dev-server.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var flink_1 = require("@flink-app/flink");
+var path_1 = __importDefault(require("path"));
+var fs_1 = __importDefault(require("fs"));
+var app = (0, flink_1.expressFn)();
+var port = 3001;
+// Configure development options
+var options = {
+    apiPath: "/docs/api",
+};
+// Load sample data
+var sampleData;
+try {
+    sampleData = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, "../sample.json"), "utf-8"));
+    console.log("Sample data loaded successfully");
+}
+catch (error) {
+    console.error("Failed to load sample.json:", error);
+    process.exit(1);
+}
+// Enable CORS for development
+app.use(function (req, res, next) {
+    res.header("Access-Control-Allow-Origin", "*");
+    res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
+    next();
+});
+// Serve API endpoint
+app.get(options.apiPath, function (req, res) {
+    console.log("API request received at ".concat(options.apiPath));
+    res.json({
+        routes: Array.isArray(sampleData) ? sampleData : [sampleData],
+    });
+});
+// Start the server
+app.listen(port, function () {
+    console.log("Mock API server running at http://localhost:".concat(port));
+    console.log("API endpoint available at http://localhost:".concat(port).concat(options.apiPath));
+    console.log("\nTo develop the React app:");
+    console.log("1. Keep this server running");
+    console.log("2. In another terminal, cd to react-app and run 'npm run dev'");
+    console.log("3. Open http://localhost:5173 to see the app");
+});

package/dist/index.d.ts

@@ -2,8 +2,14 @@ import { FlinkPlugin } from "@flink-app/flink";
 export type ApiDocOptions = {
     /**
      * Path to where api docs can be accessed
+     * Defaults to "/docs"
      */
     path?: string;
+    /**
+     * Path to where route and schemas are fetched from.
+     * Defaults to "/docs/api"
+     */
+    apiPath?: string;
     /**
      * Name of plugin
      */

package/dist/index.js

@@ -1,7 +1,10 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.apiDocPlugin = void 0;
-var path_1 = require("path");
+var path_1 = __importDefault(require("path"));
 var apiDocPlugin = function (options) {
     if (options === void 0) { options = {}; }
     return {
@@ -11,23 +14,15 @@ var apiDocPlugin = function (options) {
 };
 exports.apiDocPlugin = apiDocPlugin;
 function init(app, options) {
-    // TODO: Use parsedHandlerConfig
     var expressApp = app.expressApp, handlers = app.handlers;
     if (!expressApp) {
         // should not happen
         throw new Error("Express app not initialized");
     }
-    // NOTE: This will probably break if any other plugin "claims" pug as view engine
-    expressApp.engine("pug", require("pug").__express);
-    expressApp.set("views", (0, path_1.join)(__dirname, "views"));
-    expressApp.set("view engine", "pug");
-    expressApp === null || expressApp === void 0 ? void 0 : expressApp.get(options.path || "/docs", function (req, res) {
-        var sortedHandlers = handlers.sort(function (routeA, routeB) {
-            return routeA.routeProps.path.localeCompare(routeB.routeProps.path);
-        });
-        res.render("index", {
-            title: options.title || "API Docs",
-            handlers: sortedHandlers,
-        });
+    var staticPath = path_1.default.resolve(__dirname, "react-app");
+    expressApp === null || expressApp === void 0 ? void 0 : expressApp.use(options.path || "/docs", expressApp.static(staticPath));
+    expressApp === null || expressApp === void 0 ? void 0 : expressApp.get(options.apiPath || "/docs/api", function (req, res) {
+        var sortedHandlers = handlers.sort(function (routeA, routeB) { return routeA.routeProps.path.localeCompare(routeB.routeProps.path); });
+        res.json({ routes: sortedHandlers });
     });
 }

package/dist/react-app/api-docs-favicon.svg

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="32px" height="32px" viewBox="0 0 32 32" version="1.1" xmlns="http://www.w3.org/2000/svg">
+    <title>API Docs Favicon</title>
+    <g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <!-- Document outline -->
+        <path d="M6,2 L20,2 L26,8 L26,28 L6,28 Z" fill="#FFFFFF" stroke="#2563EB" stroke-width="2" />
+        <!-- Folded corner -->
+        <path d="M20,2 L20,8 L26,8 Z" fill="#E5E7EB" stroke="#2563EB" stroke-width="2" />
+        <!-- Document lines -->
+        <line x1="10" y1="14" x2="22" y2="14" stroke="#2563EB" stroke-width="2" />
+        <line x1="10" y1="18" x2="22" y2="18" stroke="#2563EB" stroke-width="2" />
+        <line x1="10" y1="22" x2="18" y2="22" stroke="#2563EB" stroke-width="2" />
+    </g>
+</svg>