@visulima/jsdoc-open-api 2.0.76 → 2.0.78

package/README.md

@@ -1,9 +1,16 @@
 <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.
-
+    Generate OpenAPI (Swagger) specifications automatically from your JSDoc comments.
+    <br />
+    This package parses your existing code comments to create comprehensive API documentation, saving you time and effort.
+    <br />
+    It is designed for speed and minimal runtime overhead, building upon the foundations of JSDoc and Swagger standards.
+  </p>
+  <p>
+    <small>
+      <i>Note: This package originated as a fork of <a href="https://github.com/bee-travels/openapi-comment-parser" target="_blank" rel="noopener noreferrer">openapi-comment-parser</a> and <a href="https://github.com/Surnet/swagger-jsdoc" target="_blank" rel="noopener noreferrer">swagger-jsdoc</a>.</i>
+    </small>
   </p>
 </div>
 
@@ -27,6 +34,15 @@ Visulima jsdoc-open-api parser and generator is a forked version of [openapi-com
 
 ---
 
+## Features
+
+- **Automatic Generation:** Creates OpenAPI specs from JSDoc comments.
+- **Multiple Syntaxes:** Supports standard OpenAPI YAML/JSON within comments and a concise short syntax.
+- **CLI Tool:** Provides a command-line interface for easy generation.
+- **Programmatic API:** Offers a JavaScript API for integration into build processes.
+- **Framework Integration:** Includes helpers like a Webpack plugin (useful for Next.js).
+- **Performance:** Focused on speed and low overhead.
+
 ## Installation
 
 ```sh
@@ -41,95 +57,202 @@ yarn add @visulima/jsdoc-open-api
 pnpm add @visulima/jsdoc-open-api
 ```
 
-## Usage
+## Usage Overview
+
+You can use `@visulima/jsdoc-open-api` in several ways:
+
+1.  **Via Command Line (CLI):** Quick generation for simple use cases or manual runs.
+2.  **Programmatically:** Integrate generation into your custom scripts or build tools.
+3.  **With Webpack (e.g., Next.js):** Automate generation during your build process.
 
-Choose the syntax you want to use for your OpenAPI definitions:
+Choose the syntax you prefer for defining OpenAPI details within your JSDoc comments:
 
 ![choose the syntax](./__assets__/swagger-difference.png)
 
-### CLI:
+---
 
-#### To use the CLI, you need to install this missing packages:
+## Usage with CLI
 
-```sh
-npm install cli-progress commander
-```
+The Command Line Interface (CLI) provides a straightforward way to generate your OpenAPI specification.
 
-```sh
-yarn add cli-progress commander
+### Running via Package Managers
+
+Instead of installing the CLI globally or relying on optional dependencies, you can run the installed binary directly using your package manager:
+
+```bash
+# With npx (comes with npm)
+npx jsdoc-open-api generate src/
+# Or explicitly using the package name:
+npx @visulima/jsdoc-open-api generate src/
+
+# With pnpm
+pnpm exec jsdoc-open-api generate src/
+
+# With Yarn 1.x
+yarn run jsdoc-open-api generate src/
+
+# With Yarn Berry (2+)
+yarn jsdoc-open-api generate src/
 ```
 
+This is often the recommended way to use package binaries within a project.
+
+### Optional Dependencies
+
+The CLI relies on `commander` and `cli-progress`. These are listed as `optionalDependencies`. Depending on your package manager (npm/yarn/pnpm) and configuration, you _might_ need to install them manually if they weren't installed automatically:
+
 ```sh
-pnpm add cli-progress commander
+# If needed:
+npm install commander cli-progress
+# or
+yarn add commander cli-progress
+# or
+pnpm add commander cli-progress
 ```
 
-#### Than you can use the CLI like this:
+### Commands
+
+#### `init`
+
+Initializes the project by creating a `.openapirc.js` configuration file. This is typically run once per project.
 
 ```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/
+#### `generate`
+
+Parses your source files based on the configuration (or command-line arguments) and generates the OpenAPI specification file.
+
+```bash
+# Generate using defaults defined in .openapirc.js (if it exists)
+jsdoc-open-api generate
+
+# Specify input path(s) directly
+jsdoc-open-api generate src/routes/**/*.js src/controllers/
+
+# Specify output file
+jsdoc-open-api generate -o ./public/swagger.json src/
+
+# Use verbose output
+jsdoc-open-api generate -v src/
+
+# Use very verbose output for debugging
+jsdoc-open-api generate -d src/
 ```
 
-### As Next.js webpack plugin:
+### `generate` Command Options:
 
-#### with-open-api.js
+```bash
+jsdoc-open-api generate [options] [path ...]
+```
+
+- `[path ...]` : Paths to files or directories to parse (optional, uses configuration if not provided).
+- `-c, --config [.openapirc.js]` : Specify the configuration file path. Defaults to `.openapirc.js`.
+- `-o, --output [swaggerSpec.json]` : Specify the output file for the OpenAPI specification. Defaults to `swaggerSpec.json`.
+- `-v, --verbose` : Enable verbose output during generation.
+- `-d, --very-verbose` : Enable _very_ verbose output for detailed debugging.
+
+---
+
+## Programmatic Usage
+
+You can integrate the generation process directly into your Node.js scripts.
+
+```javascript
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import jsdocOpenApi from "@visulima/jsdoc-open-api"; // Adjust import based on your module system (require vs import)
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const options = {
+    definition: {
+        openapi: "3.0.0",
+        info: {
+            title: "My Programmatic API",
+            version: "1.0.0",
+            description: "API documentation generated programmatically",
+        },
+        // Add other base OpenAPI definition properties here
+    },
+    // Glob patterns pointing to your source files with JSDoc comments
+    sources: [path.join(__dirname, "src/routes/**/*.js")],
+    // Optional: Specify output path (defaults to 'swaggerSpec.json' in current dir)
+    // output: path.join(__dirname, 'public/api-docs.json'),
+    // Optional: Enable verbose logging
+    // verbose: true,
+};
+
+async function generateDocs() {
+    try {
+        const specification = await jsdocOpenApi(options);
+        console.log("OpenAPI specification generated successfully:");
+        // The specification object is returned, and also written to the output file if specified.
+        // console.log(JSON.stringify(specification, null, 2));
+    } catch (error) {
+        console.error("Error generating OpenAPI specification:", error);
+    }
+}
+
+generateDocs();
+```
+
+---
+
+## Usage with Next.js (via Webpack Plugin)
+
+The package includes a Webpack plugin for seamless integration with frameworks like Next.js.
+
+### `with-open-api.js` Helper
+
+Create a helper file (e.g., `with-open-api.js`) in your project root:
 
 ```js
 const path = require("node:path");
 const fs = require("node:fs");
+// Adjust the import path based on your project structure if needed
 const { SwaggerCompilerPlugin } = require("@visulima/jsdoc-open-api");
 
 /**
- * @param definition {import('@visulima/jsdoc-open-api').SwaggerDefinition}
- * @param sources {string[]}
- * @param verbose {boolean}
- * @param output {string}
+ * @param {object} options
+ * @param {import('@visulima/jsdoc-open-api').SwaggerDefinition} options.definition - Base OpenAPI definition.
+ * @param {string[]} options.sources - Glob patterns for source files relative to project root.
+ * @param {boolean} [options.verbose=false] - Enable verbose logging.
+ * @param {string} [options.output='swagger/swagger.json'] - Output path relative to project root.
  *
- * @returns {function(*): *&{webpack: function(Configuration, *): (Configuration)}}
+ * @returns {function(import('next').NextConfig): import('next').NextConfig & {webpack: function(import('webpack').Configuration, object): import('webpack').Configuration}}
  */
 const withOpenApi =
     ({ definition, sources, verbose, output = "swagger/swagger.json" }) =>
-    (nextConfig) => {
+    (nextConfig = {}) => {
         return {
             ...nextConfig,
             webpack: (config, options) => {
+                // Run generation only on the server build in Next.js
                 if (!options.isServer) {
                     return config;
                 }
 
-                if (output.startsWith("/")) {
-                    output = output.slice(1);
+                let outputPath = output;
+                if (outputPath.startsWith("/")) {
+                    outputPath = outputPath.slice(1);
                 }
 
-                if (!output.endsWith(".json")) {
+                if (!outputPath.endsWith(".json")) {
+                    // Consider allowing YAML output as well?
                     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 },
-                        ),
-                    ],
-                };
+                const absoluteOutputPath = path.join(options.dir, outputPath);
+                const absoluteSourcePaths = sources.map((source) => path.join(options.dir, source.replace(/^\.\//, ""))); // Normalize paths
 
+                // Add the SwaggerCompilerPlugin to webpack plugins
+                config.plugins = config.plugins || [];
+                config.plugins.push(new SwaggerCompilerPlugin(absoluteOutputPath, absoluteSourcePaths, definition, { verbose }));
+
+                // Call the original webpack config function if it exists
                 if (typeof nextConfig.webpack === "function") {
                     return nextConfig.webpack(config, options);
                 }
@@ -142,204 +265,274 @@ const withOpenApi =
 module.exports = withOpenApi;
 ```
 
-#### Next.config.js
+### `next.config.js`
+
+Wrap your Next.js configuration with the helper:
 
 ```js
-const withOpenApi = require("./with-open-api");
+const withOpenApi = require("./with-open-api"); // Adjust path if necessary
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
     reactStrictMode: true,
     swcMinify: true,
     env: {
-        NEXT_PUBLIC_APP_ORIGIN: process.env.VERCEL_URL || "http://localhost:3001",
+        NEXT_PUBLIC_APP_ORIGIN: process.env.VERCEL_URL || "http://localhost:3000", // Default to 3000?
     },
+    // ... other Next.js config
 };
 
 module.exports = withOpenApi({
     definition: {
         openapi: "3.0.0",
         info: {
-            title: "My API",
+            title: "My Next.js API",
             version: "1.0.0",
         },
+        // servers: [{ url: '/api' }], // Optional: Define servers
     },
-    sources: ["pages/api"],
-    verbose: false, // default is false
+    // Paths relative to your project root
+    sources: ["pages/api/**/*.js", "src/controllers/**/*.js"],
+    output: "public/swagger.json", // Output to the public folder
+    verbose: false,
 })(nextConfig);
 ```
 
-## OpenApi YAML syntax
+Now, the OpenAPI specification (`public/swagger.json`) will be generated automatically during your Next.js build.
+
+---
+
+## Configuration (`.openapirc.js`)
+
+When using the CLI `generate` command without specifying paths or using the `init` command, `@visulima/jsdoc-open-api` looks for a `.openapirc.js` file in your project root. This file should export an options object similar to the one used in Programmatic Usage:
+
+```javascript
+// .openapirc.js
+module.exports = {
+    definition: {
+        openapi: "3.0.0",
+        info: {
+            title: "API from Config",
+            version: "2.0.0",
+        },
+        // ... other base definition properties
+    },
+    // Array of glob patterns for your source files
+    sources: ["src/**/*.js", "routes/**/*.js"],
+    output: "docs/swagger.json", // Default output file path
+    verbose: false, // Default verbosity
+};
+```
+
+---
+
+## Defining OpenAPI Specs in JSDoc
 
-The library will take the contents of @openapi (or @swagger):
+You have two main ways to define your API specifications within JSDoc comments:
+
+### 1. Standard OpenAPI (YAML/JSON) Syntax
+
+Embed standard OpenAPI 3.0 YAML or JSON directly within `@openapi` or `@swagger` blocks. The library extracts and merges these definitions.
+
+```javascript
+/**
+ * @openapi
+ * components:
+ *   schemas:
+ *     User:
+ *       type: object
+ *       properties:
+ *         id:
+ *           type: integer
+ *           format: int64
+ *           example: 10
+ *         username:
+ *           type: string
+ *           example: 'theUser'
+ *         firstName:
+ *           type: string
+ *           example: 'John'
+ *         lastName:
+ *           type: string
+ *           example: 'Doe'
+ *       required:
+ *         - id
+ *         - username
+ */
 
-```ts
 /**
  * @openapi
- * /:
+ * /users/{userId}:
  *   get:
- *     description: Welcome to swagger-jsdoc!
+ *     summary: Get user by ID
+ *     description: Retrieve detailed information about a specific user.
+ *     tags:
+ *       - Users
+ *     parameters:
+ *       - name: userId
+ *         in: path
+ *         required: true
+ *         description: ID of the user to retrieve.
+ *         schema:
+ *           type: integer
+ *           format: int64
  *     responses:
- *       200:
- *         description: Returns a mysterious string.
+ *       '200':
+ *         description: Successful response with user data.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/User' # Reference the schema defined above
+ *       '404':
+ *         description: User not found.
  */
+function getUserById(userId) {
+    // Implementation...
+}
 ```
 
-## OpenApi short syntax
+### 2. OpenApi Short Syntax
 
-### Basic structure
+Use custom JSDoc tags for a more concise way to define paths, operations, parameters, and responses.
 
-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.
+#### Basic Structure
 
-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:
+Define the HTTP method and path, followed by tags like `@summary`, `@description`, `@response`, etc.
 
-```js
+```javascript
 /**
  * GET /users
  * @summary Returns a list of users.
  * @description Optional extended description in CommonMark or HTML.
+ * @tags Users
  * @response 200 - A JSON array of user names
  * @responseContent {string[]} 200.application/json
  */
+function listUsers() {
+    // Implementation...
+}
 ```
 
 #### 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:
+Use `@pathParam`, `@queryParam`, `@headerParam`, `@cookieParam` to define parameters.
 
-```js
+```javascript
 /**
  * GET /users/{userId}
  * @summary Returns a user by ID.
- * @pathParam {int64} userId - Parameter description in CommonMark or HTML.
+ * @tags Users
+ * @pathParam {integer | int64} userId - The ID of the user to retrieve. {required}
+ * @queryParam {string} [role] - Filter users by role (optional). Possible values: 'admin', 'member'.
  * @response 200 - OK
+ * @responseContent {User} 200.application/json - A user object (assuming 'User' schema is defined elsewhere).
  */
+function getUser(userId, role) {
+    // Implementation...
+}
 ```
 
-For more information, see [Describing Parameters](/docs/short/describing-parameters.md).
-
-#### Request body
+#### 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.
+Use `@bodyContent` to describe the request body and `@bodyRequired` if it's mandatory.
 
-```js
+```javascript
 /**
  * POST /users
- * @summary Creates a user.
- * @bodyContent {User} application/json
+ * @summary Creates a new user.
+ * @tags Users
+ * @bodyContent {User} application/json - User object to create.
  * @bodyRequired
- * @response 201 - Created
+ * @response 201 - User created successfully.
+ * @responseContent {User} 201.application/json - The created user object.
  */
+function createUser(userData) {
+    // Implementation...
+}
 ```
 
-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:
+Define responses using `@response` for the status code and description, and `@responseContent` for the body schema.
 
-```js
+```javascript
 /**
- * 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
+ * GET /products/{productId}
+ * @summary Get product details.
+ * @tags Products
+ * @pathParam {string} productId - ID of the product.
+ * @response 200 - Product details.
+ * @responseContent {ProductSchema} 200.application/json
+ * @response 404 - Product 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"
+function getProduct(productId) {
+    // Implementation...
 }
 ```
 
-Can be represented as:
-
-```yaml
-components:
-    schemas:
-        User:
-            properties:
-                id:
-                    type: integer
-                name:
-                    type: string
-            # Both properties are required
-            required:
-                - id
-                - name
-```
+#### Input and Output Models (Schema References)
 
-And then referenced in the request body schema and response body schema as follows:
+Reference schemas defined globally (usually using the standard `@openapi` syntax in a central file or comment block) within your short syntax using type definitions like `{User}` or `{ProductSchema}`.
 
-```js
-/**
- * GET /users/{userId}
- * @summary Returns a user by ID.
- * @pathParam {integer} userId
- * @response 200 - OK
- * @responseContent {User} 200.application/json
- */
+```javascript
+// Assuming 'User' schema is defined in components/schemas
 
 /**
- * POST /users
- * @summary Creates a new user.
- * @bodyContent {User} application/json
+ * PUT /users/{userId}
+ * @summary Update an existing user.
+ * @tags Users
+ * @pathParam {integer} userId - ID of the user to update.
+ * @bodyContent {User} application/json - Updated user data.
  * @bodyRequired
- * @response 201 - Created
+ * @response 200 - User updated successfully.
+ * @responseContent {User} 200.application/json
+ * @response 404 - User not found.
  */
+function updateUser(userId, userData) {
+    // Implementation...
+}
 ```
 
 #### Authentication
 
-The `securitySchemes` and `security` keywords are used to describe the authentication methods used in your API.
+Reference `securitySchemes` defined globally (using standard `@openapi` syntax) with the `@security` tag.
 
-```yaml
-components:
-    securitySchemes:
-        BasicAuth:
-            type: http
-            scheme: basic
-```
+```javascript
+// Assuming 'BasicAuth' is defined in components/securitySchemes
 
-```js
 /**
- * GET /users
+ * GET /admin/settings
+ * @summary Get administrative settings (requires auth).
+ * @tags Admin
  * @security BasicAuth
+ * @response 200 - Admin settings object.
  */
+function getAdminSettings() {
+    // Implementation...
+}
 ```
 
-Supported authentication methods are:
+For detailed information on the short syntax tags and possibilities, please refer to the documentation (link to be added if available).
+
+<!-- Add link to short syntax docs here if they exist -->
 
-- 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).
+## Contributing
 
-[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+Contributions are welcome! Please refer to the [Contribution Guidelines](../../../.github/CONTRIBUTING.md) for details on how to submit pull requests, report issues, and suggest improvements.
 
-[typescript-url]: https://www.typescriptlang.org/ "TypeScript" "typescript"
+---
+
+## License
+
+This project is licensed under the **MIT License**. See the [LICENSE.md](LICENSE.md) file for details.
+
+---
+
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]: https://www.typescriptlang.org/ "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