@scalar/nextjs-openapi 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @scalar/nextjs-openapi
+
+## 0.0.2
+
+### Patch Changes
+
+- 48d7ad5: fix: repository URL in package.json
+  - @scalar/nextjs-api-reference@0.4.84
+
+## 0.0.1
+
+### Patch Changes
+
+- cec10d5: fix(nextjs-openapi): convert next config back to js from ts
+- 44e7e75: feat(nextjs-openapi): added next.js openapi generation integration
+- Updated dependencies [44e7e75]
+- Updated dependencies [89adf75]
+  - @scalar/nextjs-api-reference@0.4.84
+  - @scalar/ts-to-openapi@0.0.1
+  - @scalar/types@0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present Scalar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# [PRE-ALPHA] Scalar Next.js API Reference Handler
+
+[![Version](https://img.shields.io/npm/v/%40scalar/nextjs-openapi)](https://www.npmjs.com/package/@scalar/nextjs-openapi)
+[![Downloads](https://img.shields.io/npm/dm/%40scalar/nextjs-openapi)](https://www.npmjs.com/package/@scalar/nextjs-openapi)
+[![License](https://img.shields.io/npm/l/%40scalar%2fnextjs-openapi)](https://www.npmjs.com/package/@scalar/nextjs-openapi)
+[![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
+
+This plugin automatically generates an OpenAPI schema file based on a Next.js API.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/scalar/scalar/assets/2039539/5837adad-a605-4edb-90ec-b929ff2b803b">
+  <source media="(prefers-color-scheme: light)" srcset="https://github.com/scalar/scalar/assets/2039539/4f58202d-f40f-47b3-aeaa-44681b424a45">
+  <img alt="Screenshot of an API Reference" src="https://github.com/scalar/scalar/assets/2039539/4f58202d-f40f-47b3-aeaa-44681b424a45">
+</picture>
+
+## Installation
+
+```bash
+npm install @scalar/nextjs-openapi
+```
+
+## Usage
+
+Currently this plugin is strictly for the app router with typescript. Currently we generate the spec from the Request/Context types as well as the returns in the HTTP method. You can find a simple example in the `playground` folder.
+
+Also is currently under heavy development, all API's are likely to change. However we are looking for feedback! If you have an open API OR would like to share a private one, let us know so we can test the integration with it.
+
+You just need to drop this file into the `app/api/openapi/[[...openapi]]` folder. You can rename the openapi folder to whatever you like but the dynamic folder must be catch-all as we will be serving two endpoints.
+
+```ts
+// app/api/openapi/[[...slug]]/route.ts
+import { OpenAPI } from '@scalar/nextjs-openapi'
+
+export const GET = OpenAPI()
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './openapi.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { OpenAPI } from './openapi.js';

package/dist/openapi.d.ts

@@ -0,0 +1,26 @@
+import type { ReferenceConfiguration } from '@scalar/types/legacy';
+import type { NextRequest } from 'next/server';
+/**
+ * Scalar OpenAPI config
+ */
+export type OpenAPIConfig = {
+    /**
+     * The base directory for your API files
+     * @default 'app/api'
+     */
+    apiDirectory?: string;
+} & ReferenceConfiguration;
+/**
+ * Scalar Next.js OpenAPI schema generation
+ *
+ * Handles both the schema generation as well as the references
+ *
+ * TODO:
+ * - Docs
+ * - file watcher
+ * - caching
+ */
+export declare const OpenAPI: (config?: OpenAPIConfig) => {
+    GET: (req: NextRequest) => Promise<Response>;
+};
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAGlE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAa9C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,GAAG,sBAAsB,CAAA;AAqC1B;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,YAAY,aAAa;eAmCxB,WAAW;CAkB/B,CAAA"}

package/dist/openapi.js

@@ -0,0 +1,86 @@
+import { ApiReference } from '@scalar/nextjs-api-reference';
+import { sync } from 'fast-glob';
+import { readFileSync } from 'fs';
+import { createSourceFile, ScriptTarget, ScriptKind, JSDocParsingMode, createProgram } from 'typescript';
+import { getPathSchema } from './path.js';
+
+// TODO switch to watcher
+// @see https://github.com/microsoft/TypeScript-wiki/blob/main/Using-the-Compiler-API.md#writing-an-incremental-program-watcher
+const compilerHost = {
+    fileExists: () => true,
+    getCanonicalFileName: (filename) => filename,
+    getCurrentDirectory: () => '',
+    getDefaultLibFileName: () => '',
+    getNewLine: () => '\n',
+    getSourceFile: (filename) => createSourceFile(filename, readFileSync(filename).toString(), ScriptTarget.Latest, false, ScriptKind.TS),
+    jsDocParsingMode: JSDocParsingMode.ParseAll,
+    readFile: () => undefined,
+    useCaseSensitiveFileNames: () => true,
+    writeFile: () => null,
+};
+/** OpenAPI 3.1.0 Spec */
+const spec = {
+    openapi: '3.1.0',
+    info: {
+        title: `${process.env.npm_package_name} - Next.js OpenAPI Spec by Scalar`,
+        description: process.env.npm_package_description ||
+            'This file has been autogenerated, check out the docs to see how to customize these options',
+        version: process.env.npm_package_version || '0.0.0',
+    },
+    paths: {},
+};
+/**
+ * Scalar Next.js OpenAPI schema generation
+ *
+ * Handles both the schema generation as well as the references
+ *
+ * TODO:
+ * - Docs
+ * - file watcher
+ * - caching
+ */
+const OpenAPI = (config = {}) => {
+    const apiDirectory = config.apiDirectory ?? 'app/api';
+    /** All ts files required for the schema */
+    const programFileNames = sync(apiDirectory + '/**/*.ts');
+    /** Specific route files to generate paths */
+    const routeFileNames = sync(apiDirectory + '/**/route.ts');
+    const program = createProgram(programFileNames, {
+        noResolve: true,
+        target: ScriptTarget.Latest,
+    }, compilerHost);
+    // Loop over all non scalar files to extract openapi data using AST
+    routeFileNames.forEach((fileName) => {
+        const sourceFile = program.getSourceFile(fileName);
+        if (sourceFile) {
+            const resp = getPathSchema(sourceFile, program);
+            // Grab the path from the fileName
+            const rawPath = fileName
+                .replace(/^app|\/route\.ts$/g, '')
+                .replace(/\[/g, '{')
+                .replace(/]/g, '}');
+            const path = rawPath.startsWith('/') ? rawPath : '/' + rawPath;
+            spec.paths[path] = resp;
+        }
+    });
+    return {
+        GET: async (req) => {
+            // OpenAPI Schema JSON
+            if (req.nextUrl.pathname.endsWith('.json')) {
+                // Just grabbing the origin here but we can be smarter and look for the greatest common few segments
+                spec.servers = [{ url: req.nextUrl.origin }];
+                return Response.json(spec);
+            }
+            // References
+            else {
+                return await ApiReference({
+                    spec: {
+                        url: req.nextUrl.pathname + '/schema.json',
+                    },
+                })();
+            }
+        },
+    };
+};
+
+export { OpenAPI };

package/dist/path.d.ts

@@ -0,0 +1,7 @@
+import type { OpenAPIV3_1 } from 'openapi-types';
+import { type Program, type SourceFile } from 'typescript';
+/**
+ * Traverse the typescript file and extract as much info as we can for the openapi spec
+ */
+export declare const getPathSchema: (sourceFile: SourceFile, program: Program) => OpenAPIV3_1.PathsObject<{}, {}>;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAGL,KAAK,OAAO,EACZ,KAAK,UAAU,EAOhB,MAAM,YAAY,CAAA;AAsDnB;;GAEG;AACH,eAAO,MAAM,aAAa,eAAgB,UAAU,WAAW,OAAO,oCAwCrE,CAAA"}

package/dist/path.js

@@ -0,0 +1,84 @@
+import { getJSDocFromNode, generateResponses, getSchemaFromTypeNode } from '@scalar/ts-to-openapi';
+import { extname, join } from 'path';
+import { isFunctionDeclaration, isVariableStatement, isParameter, isTypeLiteralNode, isPropertySignature, isIdentifier } from 'typescript';
+
+/** Check if identifier is a supported http method */
+const checkForMethod = (identifier) => {
+    const method = identifier?.escapedText?.toLowerCase();
+    return method?.match(/^(get|post|put|patch|delete|head|options)$/)
+        ? method
+        : null;
+};
+const fileNameResolver = (source, target) => {
+    const sourceExt = extname(source);
+    const targetExt = extname(target);
+    const targetRelative = target + (targetExt ? '' : sourceExt);
+    const targetPath = join(source.replace(/\/([^/]+)$/, ''), targetRelative);
+    return targetPath;
+};
+/**
+ * Takes a parameter node and returns a path parameter schema
+ */
+const extractPathParams = (node, program) => {
+    // Traverse to the params with type guards
+    if (node &&
+        isParameter(node) &&
+        node.type &&
+        isTypeLiteralNode(node.type) &&
+        node.type.members[0] &&
+        isPropertySignature(node.type.members[0]) &&
+        isIdentifier(node.type.members[0].name) &&
+        node.type.members[0].name.escapedText === 'params' &&
+        node.type.members[0].type &&
+        isTypeLiteralNode(node.type.members[0].type))
+        return node.type.members[0].type?.members.flatMap((member) => {
+            if (!isPropertySignature(member) || !member.type)
+                return [];
+            return {
+                name: member.name?.getText(),
+                schema: getSchemaFromTypeNode(member.type, program, fileNameResolver),
+                in: 'path',
+            };
+        });
+    return [];
+};
+/**
+ * Traverse the typescript file and extract as much info as we can for the openapi spec
+ */
+const getPathSchema = (sourceFile, program) => {
+    const path = {};
+    const typeChecker = program.getTypeChecker();
+    sourceFile.statements.forEach((statement) => {
+        // Function
+        if (isFunctionDeclaration(statement) && statement.name) {
+            const method = checkForMethod(statement.name);
+            if (method) {
+                const { title, description } = getJSDocFromNode(statement);
+                const parameters = extractPathParams(statement.parameters[1], program);
+                const responses = generateResponses(statement.body, typeChecker);
+                path[method] = {
+                    summary: title,
+                    description,
+                    parameters,
+                    responses,
+                };
+            }
+        }
+        // TODO: variables
+        else if (isVariableStatement(statement)) {
+            const method = checkForMethod(statement.declarationList.declarations[0].name);
+            if (method) {
+                const { title, description } = getJSDocFromNode(statement);
+                const responses = generateResponses(statement, typeChecker);
+                path[method] = {
+                    summary: title,
+                    description,
+                    responses,
+                };
+            }
+        }
+    });
+    return path;
+};
+
+export { getPathSchema };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@scalar/nextjs-openapi",
+  "description": "Automatically generate an OpenAPI schema from a Nextjs API",
+  "license": "MIT",
+  "author": "Scalar (https://github.com/scalar)",
+  "homepage": "https://github.com/scalar/scalar",
+  "bugs": "https://github.com/scalar/scalar/issues/new/choose",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scalar/scalar.git",
+    "directory": "packages/nextjs-openapi"
+  },
+  "keywords": [
+    "typescript",
+    "types",
+    "scalar",
+    "references"
+  ],
+  "version": "0.0.2",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "fast-glob": "^3.3.2",
+    "@scalar/nextjs-api-reference": "0.4.84",
+    "@scalar/types": "0.0.6",
+    "@scalar/ts-to-openapi": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "@types/react": "^18.2.60",
+    "@types/react-dom": "^18.2.19",
+    "next": "^14.2.5",
+    "openapi-types": "^12.1.3",
+    "typescript": "^5.5.2",
+    "@scalar/build-tooling": "0.1.10"
+  },
+  "scripts": {
+    "build": "scalar-build-rollup",
+    "dev": "next dev playground -p 5066",
+    "lint:check": "eslint .",
+    "lint:fix": "eslint .  --fix",
+    "types:build": "scalar-types-build",
+    "types:check": "scalar-types-check"
+  }
+}