@nerest/nerest 0.0.2 → 0.0.3

package/README.md

@@ -30,6 +30,8 @@ The app directory may contain an `examples` subdirectory with example JSON files
 
 The app directory should contain a `schema.json` file that describes the schema of a request body for this specific app in the [JSON Schema language](https://json-schema.org/). All requests sent to this app, and app examples from the `examples` subdirectory will be validated against this schema. `ajv` and `ajv-formats` are used for validation, so all JSON Schema features implemented by them are supported.
 
+OpenAPI specification is compiled automatically based on the provided schemas and becomes available at `/api/json`. It can also be explored through Swagger UI that becomes available at `/api`.
+
 ## Development
 
 Run the build script to build the framework.

package/dist/server/index.js

@@ -13,6 +13,7 @@ const apps_1 = require("./apps");
 const render_1 = require("./render");
 const preview_1 = require("./preview");
 const validator_1 = require("./validator");
+const swagger_1 = require("./swagger");
 // TODO: this turned out to be a dev server, production server
 // will most likely be implemented separately
 async function createServer() {
@@ -52,6 +53,7 @@ async function createServer() {
     // we can use both to validate request bodies and examples against
     // app schemas
     app.setValidatorCompiler(({ schema }) => validator_1.validator.compile(schema));
+    await (0, swagger_1.setupSwagger)(app);
     for (const appEntry of Object.values(apps)) {
         const { name, entry, examples, schema } = appEntry;
         const routeOptions = {};
@@ -59,7 +61,15 @@ async function createServer() {
         // TODO: disallow apps without schemas in production build
         if (schema) {
             routeOptions.schema = {
-                body: schema,
+                // Use description as Swagger summary, since summary is visible
+                // even when the route is collapsed in the UI
+                summary: schema.description,
+                body: {
+                    ...schema,
+                    // Mix examples into the schema so they become accessible
+                    // in the Swagger UI
+                    examples: Object.values(examples),
+                },
             };
         }
         // POST /api/{name} -> render app with request.body as props
@@ -79,7 +89,14 @@ async function createServer() {
             }
             // GET /api/{name}/examples/{example} -> render a preview page
             // with a predefined example body
-            app.get(`/api/${name}/examples/${exampleName}`, async (_, reply) => {
+            const exampleRoute = `/api/${name}/examples/${exampleName}`;
+            app.get(exampleRoute, {
+                schema: {
+                    // Add a clickable link to the example route in route's Swagger
+                    // description so it's easier to navigate to
+                    description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
+                },
+            }, async (_, reply) => {
                 const ssrComponent = await viteSsr.ssrLoadModule(entry, {
                     fixStacktrace: true,
                 });
@@ -90,7 +107,7 @@ async function createServer() {
         }
     }
     // TODO: only do this locally, load from CDN in production
-    app.register(static_1.default, {
+    await app.register(static_1.default, {
         root: path_1.default.join(root, 'dist'),
         // TODO: maybe use @fastify/cors instead
         setHeaders(res) {

package/dist/server/swagger.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyInstance } from 'fastify';
+export declare function setupSwagger(app: FastifyInstance): Promise<void>;

package/dist/server/swagger.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupSwagger = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const swagger_1 = __importDefault(require("@fastify/swagger"));
+const swagger_ui_1 = __importDefault(require("@fastify/swagger-ui"));
+// Setup automatic OpenAPI specification compilation and enable
+// Swagger UI at the `/api` route
+async function setupSwagger(app) {
+    let appInfo = {};
+    try {
+        const packageJson = fs_1.default.readFileSync(path_1.default.join(process.cwd(), 'package.json'), { encoding: 'utf-8' });
+        appInfo = JSON.parse(packageJson);
+    }
+    catch (e) {
+        // We only use package.json info to setup Swagger info and links,
+        // if we are unable to load them -- that's fine
+    }
+    const homepage = appInfo.homepage ||
+        (typeof appInfo.repository === 'string'
+            ? appInfo.repository
+            : appInfo.repository?.url);
+    await app.register(swagger_1.default, {
+        openapi: {
+            info: {
+                title: appInfo.name ?? 'Nerest micro frontend',
+                description: appInfo.description,
+                version: appInfo.version ?? '',
+                contact: homepage
+                    ? {
+                        name: 'Homepage',
+                        url: homepage,
+                    }
+                    : undefined,
+            },
+            externalDocs: {
+                url: 'https://github.com/nerestjs/nerest',
+                description: 'Built with Nerest',
+            },
+        },
+    });
+    await app.register(swagger_ui_1.default, {
+        routePrefix: '/api',
+    });
+}
+exports.setupSwagger = setupSwagger;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerest/nerest",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "React micro frontend framework",
   "homepage": "https://github.com/nerestjs/nerest#readme",
   "repository": {
@@ -47,6 +47,8 @@
   },
   "dependencies": {
     "@fastify/static": "^6.9.0",
+    "@fastify/swagger": "^8.3.1",
+    "@fastify/swagger-ui": "^1.4.0",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
     "fast-uri": "^2.2.0",

package/server/index.ts

@@ -14,6 +14,7 @@ import { loadApps } from './apps';
 import { renderApp } from './render';
 import { renderPreviewPage } from './preview';
 import { validator } from './validator';
+import { setupSwagger } from './swagger';
 
 // TODO: this turned out to be a dev server, production server
 // will most likely be implemented separately
@@ -60,6 +61,8 @@ export async function createServer() {
   // app schemas
   app.setValidatorCompiler(({ schema }) => validator.compile(schema));
 
+  await setupSwagger(app);
+
   for (const appEntry of Object.values(apps)) {
     const { name, entry, examples, schema } = appEntry;
 
@@ -69,7 +72,15 @@ export async function createServer() {
     // TODO: disallow apps without schemas in production build
     if (schema) {
       routeOptions.schema = {
-        body: schema,
+        // Use description as Swagger summary, since summary is visible
+        // even when the route is collapsed in the UI
+        summary: schema.description as string,
+        body: {
+          ...schema,
+          // Mix examples into the schema so they become accessible
+          // in the Swagger UI
+          examples: Object.values(examples),
+        },
       };
     }
 
@@ -98,25 +109,36 @@ export async function createServer() {
 
       // GET /api/{name}/examples/{example} -> render a preview page
       // with a predefined example body
-      app.get(`/api/${name}/examples/${exampleName}`, async (_, reply) => {
-        const ssrComponent = await viteSsr.ssrLoadModule(entry, {
-          fixStacktrace: true,
-        });
-        const { html, assets } = renderApp(
-          appEntry,
-          ssrComponent.default,
-          example as Record<string, unknown>
-        );
-
-        reply.type('text/html');
-
-        return renderPreviewPage(html, assets);
-      });
+      const exampleRoute = `/api/${name}/examples/${exampleName}`;
+      app.get(
+        exampleRoute,
+        {
+          schema: {
+            // Add a clickable link to the example route in route's Swagger
+            // description so it's easier to navigate to
+            description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
+          },
+        },
+        async (_, reply) => {
+          const ssrComponent = await viteSsr.ssrLoadModule(entry, {
+            fixStacktrace: true,
+          });
+          const { html, assets } = renderApp(
+            appEntry,
+            ssrComponent.default,
+            example as Record<string, unknown>
+          );
+
+          reply.type('text/html');
+
+          return renderPreviewPage(html, assets);
+        }
+      );
     }
   }
 
   // TODO: only do this locally, load from CDN in production
-  app.register(fastifyStatic, {
+  await app.register(fastifyStatic, {
     root: path.join(root, 'dist'),
     // TODO: maybe use @fastify/cors instead
     setHeaders(res: ServerResponse) {

package/server/swagger.ts

@@ -0,0 +1,58 @@
+import path from 'path';
+import fs from 'fs';
+import type { FastifyInstance } from 'fastify';
+import fastifySwagger from '@fastify/swagger';
+import fastifySwaggerUi from '@fastify/swagger-ui';
+
+// Setup automatic OpenAPI specification compilation and enable
+// Swagger UI at the `/api` route
+export async function setupSwagger(app: FastifyInstance) {
+  let appInfo: {
+    name?: string;
+    description?: string;
+    version?: string;
+    homepage?: string;
+    repository?: string | { url?: string };
+  } = {};
+
+  try {
+    const packageJson = fs.readFileSync(
+      path.join(process.cwd(), 'package.json'),
+      { encoding: 'utf-8' }
+    );
+    appInfo = JSON.parse(packageJson);
+  } catch (e) {
+    // We only use package.json info to setup Swagger info and links,
+    // if we are unable to load them -- that's fine
+  }
+
+  const homepage =
+    appInfo.homepage ||
+    (typeof appInfo.repository === 'string'
+      ? appInfo.repository
+      : appInfo.repository?.url);
+
+  await app.register(fastifySwagger, {
+    openapi: {
+      info: {
+        title: appInfo.name ?? 'Nerest micro frontend',
+        description: appInfo.description,
+        version: appInfo.version ?? '',
+        contact: homepage
+          ? {
+              name: 'Homepage',
+              url: homepage,
+            }
+          : undefined,
+      },
+      externalDocs: {
+        url: 'https://github.com/nerestjs/nerest',
+        description: 'Built with Nerest',
+      },
+    },
+  });
+
+  await app.register(fastifySwaggerUi, {
+    routePrefix: '/api',
+  });
+}