@visulima/jsdoc-open-api 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## @visulima/jsdoc-open-api [1.0.3](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@1.0.2...@visulima/jsdoc-open-api@1.0.3) (2022-10-27)
+
+
+### Bug Fixes
+
+* fixed package.json files paths ([0d21e94](https://github.com/visulima/visulima/commit/0d21e94a75e9518f7b87293706615d8fb280095c))
+
+
+
+### Dependencies
+
+* **@visulima/readdir:** upgraded to 1.1.1
+
+## @visulima/jsdoc-open-api [1.0.2](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@1.0.1...@visulima/jsdoc-open-api@1.0.2) (2022-10-27)
+
+
+### Bug Fixes
+
+* **jsdoc-open-api:** fixed found errors with empty data, writing swagger file to a not existing folder, added more error returns ([8cef566](https://github.com/visulima/visulima/commit/8cef566b998d37a5c0f5c32acabf8e336510ec81))
+* **jsdoc-open-api:** fixed wrong options for minimatchOptions and added default exclude for the webpack plugin ([e6cba73](https://github.com/visulima/visulima/commit/e6cba73a5add43042249e0caff0d6d605f694274))
+
 ## @visulima/jsdoc-open-api [1.0.1](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@1.0.0...@visulima/jsdoc-open-api@1.0.1) (2022-10-26)
 
 

package/README.md

@@ -11,14 +11,22 @@
 
 <div align="center">
 
-[![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url] [![synk-image]][synk-url]
+[![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
 
 </div>
 
+---
+
 <div align="center">
-  <sub>Built with ❤︎ by <a href="https://twitter.com/_prisis_">Daniel Bannert</a></sub>
+    <p>
+        <sup>
+            Daniel Bannert's open source work is supported by the community on <a href="https://github.com/sponsors/prisis">GitHub Sponsors</a>
+        </sup>
+    </p>
 </div>
 
+---
+
 ## Installation
 
 ```sh
@@ -39,7 +47,7 @@ Choose the syntax you want to use for your OpenAPI definitions:
 
 ![choose the syntax](./assets/swagger-difference.png)
 
-CLI:
+### CLI:
 
 ```bash
 # This generate the .openapirc.js config file, this command is only needed on the first run
@@ -49,6 +57,96 @@ jsdoc-open-api init
 jsdoc-open-api generate src/
 ```
 
+### As Next.js webpack plugin:
+
+#### with-open-api.js
+```js
+
+const path = require("node:path");
+const fs = require("node:fs");
+const { SwaggerCompilerPlugin } = require("@visulima/jsdoc-open-api");
+
+/**
+ * @param definition {import('@visulima/jsdoc-open-api').SwaggerDefinition}
+ * @param sources {string[]}
+ * @param verbose {boolean}
+ * @param output {string}
+ *
+ * @returns {function(*): *&{webpack: function(Configuration, *): (Configuration)}}
+ */
+const withOpenApi = ({ definition, sources, verbose, output = "swagger/swagger.json" }) => (nextConfig) => {
+    return {
+        ...nextConfig,
+        webpack: (config, options) => {
+            if (!options.isServer) {
+                return config;
+            }
+
+            if (output.startsWith("/")) {
+                output = output.slice(1);
+            }
+
+            if (!output.endsWith(".json")) {
+                throw new Error("The output path must end with .json");
+            }
+
+            // eslint-disable-next-line no-param-reassign
+            config = {
+                ...config,
+                plugins: [
+                // @ts-ignore
+                    ...config.plugins,
+                    new SwaggerCompilerPlugin(`${options.dir}/${output}`, sources.map((source) => {
+                        const combinedPath = path.join(options.dir, source.replace("./", ""));
+
+                        // Check if the path is a directory
+                        fs.lstatSync(combinedPath).isDirectory();
+
+                        return combinedPath;
+                    }), definition, { verbose }),
+                ],
+            };
+
+            if (typeof nextConfig.webpack === "function") {
+                return nextConfig.webpack(config, options);
+            }
+
+            return config;
+        },
+    };
+};
+
+module.exports = withOpenApi;
+```
+
+#### next.config.js
+```js
+const withOpenApi = require("./with-open-api");
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+    reactStrictMode: true,
+    swcMinify: true,
+    env: {
+        NEXT_PUBLIC_APP_ORIGIN: process.env.VERCEL_URL || "http://localhost:3001",
+    }
+};
+
+module.exports = withOpenApi({
+    definition: {
+        openapi: "3.0.0",
+        info: {
+            title: "My API",
+            version: "1.0.0",
+        },
+    },
+    sources: [
+         "pages/api",
+    ],
+    verbose: false, // default is false
+})(nextConfig);
+```
+
 ## OpenApi yaml syntax
 
 The library will take the contents of @openapi (or @swagger):
@@ -214,7 +312,5 @@ For more information, see [Authentication](/docs/short/authentication.md).
 [typescript-url]: "typescript"
 [license-image]: https://img.shields.io/npm/l/@visulima/jsdoc-open-api?color=blueviolet&style=for-the-badge
 [license-url]: LICENSE.md "license"
-[npm-image]: https://img.shields.io/npm/v/@visulima/jsdoc-open-api/alpha.svg?style=for-the-badge&logo=npm
-[npm-url]: https://www.npmjs.com/package/@visulima/jsdoc-open-api/v/alpha "npm"
-[synk-image]: https://img.shields.io/snyk/vulnerabilities/github/visulima/jsdoc-open-api?label=Synk%20Vulnerabilities&style=for-the-badge
-[synk-url]: https://snyk.io/test/github/visulima/jsdoc-open-api?targetFile=package.json "synk"
+[npm-image]: https://img.shields.io/npm/v/@visulima/jsdoc-open-api/latest.svg?style=for-the-badge&logo=npm
+[npm-url]: https://www.npmjs.com/package/@visulima/jsdoc-open-api/v/latest "npm"

package/bin/index.js

@@ -4,6 +4,8 @@ const path = require("node:path");
 // eslint-disable-next-line unicorn/prefer-module
 const fs = require("node:fs");
 // eslint-disable-next-line unicorn/prefer-module
+const { exit } = require("node:process");
+// eslint-disable-next-line unicorn/prefer-module
 const { Command } = require("commander");
 // eslint-disable-next-line unicorn/prefer-module
 const SwaggerParser = require("@apidevtools/swagger-parser");
@@ -13,8 +15,11 @@ const { collect } = require("@visulima/readdir");
 const cliProgress = require("cli-progress");
 
 const {
-    jsDocumentCommentsToOpenApi, parseFile, SpecBuilder, swaggerJsDocumentCommentsToOpenApi,
-// eslint-disable-next-line unicorn/prefer-module
+    jsDocumentCommentsToOpenApi,
+    parseFile,
+    SpecBuilder,
+    swaggerJsDocumentCommentsToOpenApi,
+    // eslint-disable-next-line unicorn/prefer-module
 } = require("../dist/index.js");
 
 // eslint-disable-next-line unicorn/prefer-module,no-underscore-dangle
@@ -32,8 +37,7 @@ program
         if (fs.existsSync(defaultConfigName)) {
             // eslint-disable-next-line no-console
             console.error("Config file already exists");
-            // eslint-disable-next-line no-undef
-            process.exit(1);
+            exit(1);
         }
 
         fs.writeFileSync(
@@ -58,9 +62,8 @@ program
     '**/node_modules/**',
     '**/pnpm-lock.yaml',
     '**/pnpm-workspace.yaml',
-    '**/package-lock.json',
+    '**/{package,package-lock}.json',
     '**/yarn.lock',
-    '**/package.json',
     '**/package.json5',
     '**/.next/**',
   ],
@@ -101,8 +104,7 @@ program
             console.log("No config file found, on:", options.config || ".openapirc.js\n");
             // eslint-disable-next-line no-console
             console.error(error);
-            // eslint-disable-next-line no-undef
-            process.exit(1);
+            exit(1);
         }
 
         const multibar = new cliProgress.MultiBar(
@@ -117,6 +119,9 @@ program
 
         // eslint-disable-next-line no-restricted-syntax,unicorn/prevent-abbreviations
         for await (const dir of paths) {
+            // Check if the path is a directory
+            fs.lstatSync(dir).isDirectory();
+
             const files = await collect(dir, {
                 // eslint-disable-next-line @rushstack/security/no-unsafe-regexp
                 skip: [...openapiConfig.exclude, "node_modules/**"],
@@ -124,8 +129,14 @@ program
                 followSymlinks: openapiConfig.followSymlinks || false,
                 match: openapiConfig.include,
                 minimatchOptions: {
-                    debug: options.verbose,
-                    matchBase: true,
+                    match: {
+                        debug: options.verbose,
+                        matchBase: true,
+                    },
+                    skip: {
+                        debug: options.verbose,
+                        matchBase: true,
+                    },
                 },
             });
 
@@ -149,30 +160,65 @@ program
 
                 bar.increment(1, { filename: dir });
 
-                const parsedJsDocumentFile = parseFile(file, jsDocumentCommentsToOpenApi, this.verbose);
+                try {
+                    const parsedJsDocumentFile = parseFile(file, jsDocumentCommentsToOpenApi, this.verbose);
 
-                spec.addData(parsedJsDocumentFile.map((item) => item.spec));
+                    spec.addData(parsedJsDocumentFile.map((item) => item.spec));
 
-                const parsedSwaggerJsDocumentFile = parseFile(file, swaggerJsDocumentCommentsToOpenApi, this.verbose);
+                    const parsedSwaggerJsDocumentFile = parseFile(file, swaggerJsDocumentCommentsToOpenApi, this.verbose);
 
-                spec.addData(parsedSwaggerJsDocumentFile.map((item) => item.spec));
+                    spec.addData(parsedSwaggerJsDocumentFile.map((item) => item.spec));
+                } catch (error) {
+                    // eslint-disable-next-line no-console
+                    console.error(error);
+                    exit(1);
+                }
             });
         }
 
         try {
+            if (options.verbose) {
+                // eslint-disable-next-line no-console
+                console.log("Validating swagger spec");
+            }
+
+            if (options.veryVerbose) {
+                // eslint-disable-next-line no-console
+                console.log(JSON.stringify(spec, null, 2));
+            }
+
             await SwaggerParser.validate(JSON.parse(JSON.stringify(spec)));
         } catch (error) {
             // eslint-disable-next-line no-console
             console.error(error.toJSON());
-            // eslint-disable-next-line no-undef
-            process.exit();
+            exit(1);
         }
 
         const output = options.output || "swagger.json";
 
         multibar.stop();
 
-        fs.writeFileSync(output, JSON.stringify(spec, null, 2));
+        if (options.verbose) {
+            // eslint-disable-next-line no-console
+            console.log(`Written swagger spec to "${output}" file`);
+        }
+
+        const errorHandler = (error) => {
+            if (error) {
+                // eslint-disable-next-line no-console
+                console.error(error);
+                exit(1);
+            }
+        };
+
+        // eslint-disable-next-line consistent-return
+        fs.mkdir(path.dirname(output), { recursive: true }, (error) => {
+            if (error) {
+                errorHandler(error);
+            }
+
+            fs.writeFile(output, JSON.stringify(spec, null, 2), errorHandler);
+        });
 
         // eslint-disable-next-line no-console
         console.log(`\nSwagger specification is ready, check the${output}file.`);
@@ -183,6 +229,5 @@ program.parse(process.argv);
 // eslint-disable-next-line no-undef
 if (process.argv.slice(2).length === 0) {
     program.help();
-    // eslint-disable-next-line no-undef
-    process.exit();
+    exit(1);
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Configuration } from 'webpack';
+import { Compiler } from 'webpack';
 
 interface BaseDefinition {
     openapi: string;
@@ -281,13 +281,13 @@ declare class SwaggerCompilerPlugin {
     private readonly swaggerDefinition;
     private readonly sources;
     private readonly verbose;
-    private ignore;
+    private readonly ignore;
     assetsPath: string;
     constructor(assetsPath: string, sources: string[], swaggerDefinition: BaseDefinition, options: {
         verbose?: boolean;
         ignore?: string | ReadonlyArray<string>;
     });
-    apply(compiler: Configuration): void;
+    apply(compiler: Compiler): void;
 }
 
 declare const commentsToOpenApi$1: (fileContents: string, verbose?: boolean) => {

package/dist/index.js

@@ -33,8 +33,8 @@ var SpecBuilder = class {
     parsedFile.forEach((file) => {
       const { paths, components, ...rest } = file;
       object_merge_default(this, {
-        paths,
-        components
+        paths: paths || {},
+        components: components || {}
       });
       Object.entries(rest).forEach(([key, value]) => {
         this[key] = value;
@@ -95,7 +95,8 @@ var parse_file_default = parseFile;
 // src/webpack/swagger-compiler-plugin.ts
 var _swaggerparser = require('@apidevtools/swagger-parser'); var _swaggerparser2 = _interopRequireDefault(_swaggerparser);
 var _readdir = require('@visulima/readdir');
-var _debug2 = require('debug'); var _debug3 = _interopRequireDefault(_debug2);
+
+
 var _process = require('process');
 
 // src/jsdoc/comments-to-open-api.ts
@@ -572,7 +573,36 @@ var commentsToOpenApi2 = (fileContents, verbose) => {
 var comments_to_open_api_default2 = commentsToOpenApi2;
 
 // src/webpack/swagger-compiler-plugin.ts
-var debug = _debug3.default.call(void 0, "visulima:jsdoc-open-api:swagger-compiler-plugin");
+var exclude = [
+  "coverage/**",
+  ".github/**",
+  "packages/*/test{,s}/**",
+  "**/*.d.ts",
+  "test{,s}/**",
+  "test{,-*}.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}",
+  "**/*{.,-}test.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}",
+  "**/__tests__/**",
+  "**/{ava,babel,nyc}.config.{js,cjs,mjs}",
+  "**/jest.config.{js,cjs,mjs,ts}",
+  "**/{karma,rollup,webpack}.config.js",
+  "**/.{eslint,mocha}rc.{js,cjs}",
+  "**/.{travis,yarnrc}.yml",
+  "**/{docker-compose,docker}.yml",
+  "**/.yamllint.{yaml,yml}",
+  "**/node_modules/**",
+  "**/pnpm-lock.yaml",
+  "**/pnpm-workspace.yaml",
+  "**/{package,package-lock}.json",
+  "**/yarn.lock",
+  "**/package.json5",
+  "**/.next/**"
+];
+var errorHandler = (error) => {
+  if (error) {
+    console.error(error);
+    _process.exit.call(void 0, 1);
+  }
+};
 var SwaggerCompilerPlugin = class {
   constructor(assetsPath, sources, swaggerDefinition, options) {
     this.assetsPath = assetsPath;
@@ -582,40 +612,63 @@ var SwaggerCompilerPlugin = class {
     this.ignore = options.ignore || [];
   }
   apply(compiler) {
-    compiler.hooks.make.tapAsync("SwaggerCompilerPlugin", async (compilation, callback) => {
-      console.log("Build paused");
-      console.log("switching to swagger build");
+    compiler.hooks.make.tapAsync("SwaggerCompilerPlugin", async (_, callback) => {
+      console.log("Build paused, switching to swagger build");
       const spec = new spec_builder_default(this.swaggerDefinition);
       for await (const dir of this.sources) {
         const files = await _readdir.collect.call(void 0, dir, {
-          skip: [...this.ignore, "node_modules/**"]
+          skip: [...this.ignore, ...exclude],
+          extensions: [".js", ".cjs", ".mjs", ".ts", ".tsx", ".jsx", ".yaml", ".yml"],
+          minimatchOptions: {
+            match: {
+              debug: this.verbose,
+              matchBase: true
+            },
+            skip: {
+              debug: this.verbose,
+              matchBase: true
+            }
+          }
         });
         if (this.verbose) {
           console.log(`Found ${files.length} files in ${dir}`);
           console.log(files);
         }
         files.forEach((file) => {
-          debug(`Parsing file ${file}`);
-          const parsedJsDocumentFile = parse_file_default(file, comments_to_open_api_default, this.verbose);
-          spec.addData(parsedJsDocumentFile.map((item) => item.spec));
-          const parsedSwaggerJsDocumentFile = parse_file_default(file, comments_to_open_api_default2, this.verbose);
-          spec.addData(parsedSwaggerJsDocumentFile.map((item) => item.spec));
+          if (this.verbose) {
+            console.log(`Parsing file ${file}`);
+          }
+          try {
+            const parsedJsDocumentFile = parse_file_default(file, comments_to_open_api_default, this.verbose);
+            spec.addData(parsedJsDocumentFile.map((item) => item.spec));
+            const parsedSwaggerJsDocumentFile = parse_file_default(file, comments_to_open_api_default2, this.verbose);
+            spec.addData(parsedSwaggerJsDocumentFile.map((item) => item.spec));
+          } catch (error) {
+            console.error(error);
+            _process.exit.call(void 0, 1);
+          }
         });
       }
       try {
+        if (this.verbose) {
+          console.log("Validating swagger spec");
+          console.log(JSON.stringify(spec, null, 2));
+        }
         await _swaggerparser2.default.validate(JSON.parse(JSON.stringify(spec)));
       } catch (error) {
         console.error(error.toJSON());
         _process.exit.call(void 0, 1);
       }
-      compilation.assets[this.assetsPath] = {
-        source() {
-          return JSON.stringify(spec, null, 2);
-        },
-        size() {
-          return Object.keys(spec).length;
+      const { assetsPath } = this;
+      _fs2.default.mkdir(_path.dirname.call(void 0, assetsPath), { recursive: true }, (error) => {
+        if (error) {
+          errorHandler(error);
         }
-      };
+        _fs2.default.writeFile(assetsPath, JSON.stringify(spec, null, 2), errorHandler);
+      });
+      if (this.verbose) {
+        console.log(`Written swagger spec to "${this.assetsPath}" file`);
+      }
       console.log("switching back to normal build");
       callback();
     });