@visulima/jsdoc-open-api 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+## @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)
+
+
+### Bug Fixes
+
+* **jsdoc-open-api:** make package public ([f266edf](https://github.com/visulima/visulima/commit/f266edf64fb21f2510d9ab15e27e48909d593a58))
+
+## @visulima/jsdoc-open-api 1.0.0 (2022-10-26)
+
+
+### Features
+
+* **jsdoc-open-api:** added connect as new package for swagger parsing ([a641712](https://github.com/visulima/visulima/commit/a641712ab27616d38250fdd86a6cdc5c865ddd80))
+
+
+
+### Dependencies
+
+* **@visulima/readdir:** upgraded to 1.1.0

package/README.md

@@ -0,0 +1,226 @@
+<div align="center">
+  <h3>Visulima jsdoc-open-api</h3>
+  <p>
+
+  Visulima jsdoc-open-api parser and generator is a forked version of [openapi-comment-parser](https://github.com/bee-travels/openapi-comment-parser) and [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc) its built on top of [swagger](https://swagger.io/) and [JSDoc](https://jsdoc.app/), for speed and minimal runtime overhead.
+
+  </p>
+</div>
+
+<br />
+
+<div align="center">
+
+[![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
+
+</div>
+
+---
+
+<div align="center">
+    <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
+npm install @visulima/jsdoc-open-api
+```
+
+```sh
+yarn add @visulima/jsdoc-open-api
+```
+
+```sh
+pnpm add @visulima/jsdoc-open-api
+```
+
+## Usage
+
+Choose the syntax you want to use for your OpenAPI definitions:
+
+![choose the syntax](./assets/swagger-difference.png)
+
+CLI:
+
+```bash
+# This generate the .openapirc.js config file, this command is only needed on the first run
+jsdoc-open-api init
+
+# This will generate the swagger.json file
+jsdoc-open-api generate src/
+```
+
+## OpenApi yaml syntax
+
+The library will take the contents of @openapi (or @swagger):
+
+```ts
+/**
+ * @openapi
+ * /:
+ *   get:
+ *     description: Welcome to swagger-jsdoc!
+ *     responses:
+ *       200:
+ *         description: Returns a mysterious string.
+ */
+
+```
+
+## OpenApi short syntax
+
+### Basic structure
+You can write OpenAPI definitions in JSDoc comments or YAML files.
+In this guide, we use only JSDoc comments examples. However, YAML files work equally as well.
+
+Each comment defines individual endpoints (paths) in your API, and the HTTP methods (operations) supported by these endpoints.
+For example, `GET /users` can be described as:
+
+```js
+/**
+ * GET /users
+ * @summary Returns a list of users.
+ * @description Optional extended description in CommonMark or HTML.
+ * @response 200 - A JSON array of user names
+ * @responseContent {string[]} 200.application/json
+ */
+```
+
+#### Parameters
+Operations can have parameters passed via URL path (`/users/{userId}`), query string (`/users?role=admin`),
+headers (`X-CustomHeader: Value`) or cookies (`Cookie: debug=0`).
+You can define the parameter data types, format, whether they are required or optional, and other details:
+
+```js
+/**
+ * GET /users/{userId}
+ * @summary Returns a user by ID.
+ * @pathParam {int64} userId - Parameter description in CommonMark or HTML.
+ * @response 200 - OK
+ */
+```
+
+For more information, see [Describing Parameters](/docs/short/describing-parameters.md).
+
+#### Request body
+If an operation sends a request body, use the `bodyContent` keyword to describe the body content and media type.
+Use `bodyRequired` to indicate that a request body is required.
+
+```js
+/**
+ * POST /users
+ * @summary Creates a user.
+ * @bodyContent {User} application/json
+ * @bodyRequired
+ * @response 201 - Created
+ */
+```
+
+For more information, see [Describing Request Body](/docs/short/describing-request-body.md).
+
+#### Responses
+For each operation, you can define possible status codes, such as 200 OK or 404 Not Found, and the response body content.
+You can also provide example responses for different content types:
+
+```js
+/**
+ * GET /users/{userId}
+ * @summary Returns a user by ID.
+ * @pathParam {int64} userId - The ID of the user to return.
+ * @response 200 - A user object.
+ * @responseContent {User} 200.application/json
+ * @response 400 - The specified user ID is invalid (not a number).
+ * @response 404 - A user with the specified ID was not found.
+ * @response default - Unexpected error
+ */
+```
+
+For more information, see [Describing Responses](/docs/short/describing-responses.md).
+
+#### Input and output models
+You can create global `components/schemas` section lets you define common data structures used in your API.
+They can be referenced by name whenever a schema is required – in parameters, request bodies, and response bodies.
+For example, this JSON object:
+
+```json
+{
+  "id": 4,
+  "name": "Arthur Dent"
+}
+```
+
+can be represented as:
+
+```yaml
+components:
+  schemas:
+    User:
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+      # Both properties are required
+      required:
+        - id
+        - name
+```
+
+and then referenced in the request body schema and response body schema as follows:
+
+```js
+/**
+ * GET /users/{userId}
+ * @summary Returns a user by ID.
+ * @pathParam {integer} userId
+ * @response 200 - OK
+ * @responseContent {User} 200.application/json
+ */
+
+/**
+ * POST /users
+ * @summary Creates a new user.
+ * @bodyContent {User} application/json
+ * @bodyRequired
+ * @response 201 - Created
+ */
+```
+
+#### Authentication
+The `securitySchemes` and `security` keywords are used to describe the authentication methods used in your API.
+```yaml
+components:
+  securitySchemes:
+    BasicAuth:
+      type: http
+      scheme: basic
+```
+
+```js
+/**
+ * GET /users
+ * @security BasicAuth
+ */
+```
+
+Supported authentication methods are:
+- HTTP authentication: Basic, Bearer, and so on.
+- API key as a header or query parameter or in cookies
+- OAuth 2
+- OpenID Connect Discovery
+
+For more information, see [Authentication](/docs/short/authentication.md).
+
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[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/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

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// eslint-disable-next-line unicorn/prefer-module
+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 { Command } = require("commander");
+// eslint-disable-next-line unicorn/prefer-module
+const SwaggerParser = require("@apidevtools/swagger-parser");
+// eslint-disable-next-line unicorn/prefer-module
+const { collect } = require("@visulima/readdir");
+// eslint-disable-next-line unicorn/prefer-module
+const cliProgress = require("cli-progress");
+
+const {
+    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
+const package_ = require("../package.json");
+
+const program = new Command();
+const defaultConfigName = ".openapirc.js";
+
+program.name("@visulima/jsdoc-open-api").description("CLI to to generate OpenAPI (Swagger) documentation from JSDoc's").version(package_.version);
+
+program
+    .command("init")
+    .description("Inits a pre-configured @visulima/jsdoc-open-api config file.")
+    .action(() => {
+        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);
+        }
+
+        fs.writeFileSync(
+            defaultConfigName,
+            `module.exports = {
+  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-lock.json',
+    '**/yarn.lock',
+    '**/package.json',
+    '**/package.json5',
+    '**/.next/**',
+  ],
+  followSymlinks: false,
+  swaggerDefinition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'API',
+      version: '1.0.0',
+    },
+  },
+};
+`,
+        );
+
+        // eslint-disable-next-line no-console
+        console.log("Created .openapirc.js");
+    });
+
+program
+    .command("generate")
+    .description("Generates OpenAPI (Swagger) documentation from JSDoc's")
+    .usage("[options] <path ...>")
+    .argument("[path ...]", "Paths to files or directories to parse")
+    .option("-c, --config [.openapirc.js]", "@visulima/jsdoc-open-api config file path.")
+    .option("-o, --output [swaggerSpec.json]", "Output swagger specification.")
+    .option("-v, --verbose", "Verbose output.")
+    .option("-vv, --very-verbose", "Very verbose output.")
+    // eslint-disable-next-line radar/cognitive-complexity
+    .action(async (paths, options) => {
+        let openapiConfig = {};
+
+        try {
+            // eslint-disable-next-line unicorn/prefer-module,import/no-dynamic-require
+            openapiConfig = require(path.resolve(options.config || defaultConfigName));
+        } catch (error) {
+            // eslint-disable-next-line no-console
+            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);
+        }
+
+        const multibar = new cliProgress.MultiBar(
+            {
+                clearOnComplete: false,
+                hideCursor: true,
+                format: "{value}/{total} | {bar} | {filename}",
+            },
+            cliProgress.Presets.shades_grey,
+        );
+        const spec = new SpecBuilder(openapiConfig.swaggerDefinition);
+
+        // eslint-disable-next-line no-restricted-syntax,unicorn/prevent-abbreviations
+        for await (const dir of paths) {
+            const files = await collect(dir, {
+                // eslint-disable-next-line @rushstack/security/no-unsafe-regexp
+                skip: [...openapiConfig.exclude, "node_modules/**"],
+                extensions: openapiConfig.extension || [".js", ".cjs", ".mjs", ".ts", ".tsx", ".jsx", ".yaml", ".yml"],
+                followSymlinks: openapiConfig.followSymlinks || false,
+                match: openapiConfig.include,
+                minimatchOptions: {
+                    debug: options.verbose,
+                    matchBase: true,
+                },
+            });
+
+            if (options.verbose || options.veryVerbose) {
+                // eslint-disable-next-line no-console
+                console.log(`\nFound ${files.length} files in ${dir}`);
+            }
+
+            if (options.veryVerbose) {
+                // eslint-disable-next-line no-console
+                console.log(files);
+            }
+
+            const bar = multibar.create(files.length, 0);
+
+            files.forEach((file) => {
+                if (options.verbose) {
+                    // eslint-disable-next-line no-console
+                    console.log(`Parsing file ${file}`);
+                }
+
+                bar.increment(1, { filename: dir });
+
+                const parsedJsDocumentFile = parseFile(file, jsDocumentCommentsToOpenApi, this.verbose);
+
+                spec.addData(parsedJsDocumentFile.map((item) => item.spec));
+
+                const parsedSwaggerJsDocumentFile = parseFile(file, swaggerJsDocumentCommentsToOpenApi, this.verbose);
+
+                spec.addData(parsedSwaggerJsDocumentFile.map((item) => item.spec));
+            });
+        }
+
+        try {
+            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();
+        }
+
+        const output = options.output || "swagger.json";
+
+        multibar.stop();
+
+        fs.writeFileSync(output, JSON.stringify(spec, null, 2));
+
+        // eslint-disable-next-line no-console
+        console.log(`\nSwagger specification is ready, check the${output}file.`);
+    });
+// eslint-disable-next-line no-undef
+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();
+}