apidocly 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 APIDocly
+
+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,246 @@
+# apidocly
+
+[![npm version](https://img.shields.io/npm/v/apidocly.svg)](https://www.npmjs.com/package/apidocly)
+[![npm downloads](https://img.shields.io/npm/dm/apidocly.svg)](https://www.npmjs.com/package/apidocly)
+
+API documentation generator with shadcn-style dark UI and password protection.
+
+A modern, dark-themed package that generates pure HTML/CSS/JS documentation.
+
+## Features
+
+- **apidoc-compatible**: Uses the same annotation syntax as apidoc.js
+- **Shadcn Dark UI**: Beautiful, modern dark theme inspired by shadcn/ui
+- **OpenAPI Export**: Automatically generates OpenAPI 3.0 JSON for AI tools and code generators
+- **Password Protection**: Optional client-side password protection with AES-256-GCM encryption
+- **Zero Dependencies Output**: Generated docs are pure HTML/CSS/JS - no frameworks required
+- **Single File Mode**: Generate all-in-one HTML file with embedded assets
+- **Multiple Languages**: Supports JavaScript, TypeScript, PHP, and Python
+
+## Installation
+
+```bash
+# Global installation
+npm install -g apidocly
+
+# Local installation
+npm install apidocly --save-dev
+```
+
+## Usage
+
+### Command Line
+
+```bash
+# Basic usage
+apidocly -i ./src -o ./docs
+
+# With options
+apidocly -i ./src -o ./docs --verbose --single-file
+
+# Show help
+apidocly --help
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-i, --input <path>` | Input source files path | `./` |
+| `-o, --output <path>` | Output documentation path | `./docs` |
+| `-c, --config <path>` | Path to config file | auto-detect |
+| `--private` | Include @apiPrivate methods | `false` |
+| `--single-file` | Generate single HTML file | `false` |
+| `--verbose` | Show verbose output | `false` |
+
+### Programmatic Usage
+
+```javascript
+const apidocly = require('apidocly');
+
+apidocly.generate({
+  input: './src',
+  output: './docs',
+  singleFile: false,
+  verbose: true
+}).then(result => {
+  console.log(`Generated ${result.endpoints} endpoints`);
+});
+```
+
+## Configuration
+
+Create `apidocly.json` in your project root:
+
+```json
+{
+  "name": "My API",
+  "version": "1.0.0",
+  "description": "API Documentation",
+  "title": "My API Docs",
+  "url": "https://api.example.com",
+  "sampleUrl": "https://api.example.com",
+  "password": null,
+  "passwordMessage": "Enter password to view documentation",
+  "header": {
+    "title": "Introduction",
+    "filename": "header.md"
+  },
+  "footer": {
+    "title": "Footer",
+    "filename": "footer.md"
+  }
+}
+```
+
+### Password Protection
+
+To enable password protection, add a `password` field to your config:
+
+```json
+{
+  "password": "your-password",
+  "passwordMessage": "Enter password to access API documentation"
+}
+```
+
+You can also use a pre-hashed password:
+
+```json
+{
+  "password": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+}
+```
+
+## Annotation Syntax
+
+apidocly uses the same annotation syntax as apidoc.js.
+
+### Basic Example
+
+```javascript
+/**
+ * @api {get} /users/:id Get user by ID
+ * @apiName GetUser
+ * @apiGroup Users
+ * @apiVersion 1.0.0
+ *
+ * @apiParam {Number} id User's unique ID
+ *
+ * @apiSuccess {Number} id User ID
+ * @apiSuccess {String} name User name
+ * @apiSuccess {String} email User email
+ *
+ * @apiError (Error 404) {String} error User not found
+ */
+```
+
+### Supported Annotations
+
+| Annotation | Description |
+|------------|-------------|
+| `@api {method} path [title]` | Required. Define HTTP method and path |
+| `@apiName name` | Unique identifier for the endpoint |
+| `@apiGroup name` | Group name for navigation |
+| `@apiVersion version` | API version (semver) |
+| `@apiDescription text` | Detailed description |
+| `@apiParam [(group)] [{type}] field [description]` | URL parameters |
+| `@apiQuery [(group)] [{type}] field [description]` | Query string parameters |
+| `@apiBody [(group)] [{type}] field [description]` | Request body parameters |
+| `@apiHeader [(group)] [{type}] field [description]` | Request headers |
+| `@apiSuccess [(group)] [{type}] field [description]` | Success response fields |
+| `@apiError [(group)] [{type}] field [description]` | Error response fields |
+| `@apiExample [{type}] title` | Usage examples |
+| `@apiSuccessExample [{type}] [title]` | Success response examples |
+| `@apiErrorExample [{type}] [title]` | Error response examples |
+| `@apiPermission name` | Required permission |
+| `@apiDeprecated [text]` | Mark as deprecated |
+| `@apiPrivate` | Mark as private |
+| `@apiIgnore [hint]` | Ignore this block |
+| `@apiDefine name [title]` | Define reusable block |
+| `@apiUse name` | Include defined block |
+| `@apiSampleRequest url` | Configure sample request URL |
+
+### Parameter Types
+
+```javascript
+// Basic types
+@apiParam {String} name User name
+@apiParam {Number} age User age
+@apiParam {Boolean} active Is active
+@apiParam {Object} profile User profile
+
+// Arrays
+@apiParam {String[]} tags List of tags
+
+// Optional parameters (use square brackets)
+@apiParam {String} [nickname] Optional nickname
+
+// Default values
+@apiParam {Number} [page=1] Page number
+
+// Size constraints
+@apiParam {String{..100}} name Max 100 characters
+@apiParam {String{5..}} name Min 5 characters
+@apiParam {String{5..100}} name 5-100 characters
+
+// Allowed values
+@apiParam {String="admin","user"} role User role
+```
+
+## Supported Languages
+
+| Language | File Extensions | Comment Style |
+|----------|-----------------|---------------|
+| JavaScript/TypeScript | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` | `/** */` |
+| PHP | `.php` | `/** */` |
+| Python | `.py` | `"""` docstrings |
+
+## Output Structure
+
+### Multiple Files (default)
+
+```
+docs/
+├── index.html
+├── api_data.js
+├── openapi.json      # OpenAPI 3.0 specification
+├── css/
+│   └── style.css
+└── js/
+    ├── main.js
+    └── auth.js
+```
+
+### Single File (`--single-file`)
+
+```
+docs/
+├── index.html        # All-in-one HTML
+└── openapi.json      # OpenAPI 3.0 specification
+```
+
+## OpenAPI Export
+
+Every generated documentation includes an `openapi.json` file that follows the OpenAPI 3.0 specification. This file can be used with:
+
+- **AI Assistants**: Feed to ChatGPT, Claude, or other AI tools to generate API client code
+- **Code Generators**: Use with OpenAPI Generator to create SDKs in any language
+- **API Testing Tools**: Import into Postman, Insomnia, or similar tools
+- **Type Generation**: Generate TypeScript interfaces, Zod schemas, or Pydantic models
+
+### AI Integration Example
+
+```
+You: Here's my API spec (attach openapi.json). Generate a TypeScript client with Axios.
+
+AI: Based on your OpenAPI specification, here's a complete TypeScript client...
+```
+
+## License
+
+MIT
+
+---
+
+**Website:** [apidocly.com](https://apidocly.com)

package/bin/apidocly.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const path = require('path');
+const apidocly = require('../lib/index');
+const pkg = require('../package.json');
+
+program
+  .name('apidocly')
+  .description('API documentation generator')
+  .version(pkg.version);
+
+program
+  .option('-i, --input <path>', 'Input source files path', './')
+  .option('-o, --output <path>', 'Output documentation path', './docs')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--private', 'Include @apiPrivate methods', false)
+  .option('--single-file', 'Generate single HTML file with embedded assets', false)
+  .option('--verbose', 'Show verbose output', false);
+
+program.parse();
+
+const options = program.opts();
+
+async function run() {
+  console.log(`\n  apidocly v${pkg.version}\n`);
+
+  try {
+    const inputPath = path.resolve(process.cwd(), options.input);
+    const outputPath = path.resolve(process.cwd(), options.output);
+    const configPath = options.config
+      ? path.resolve(process.cwd(), options.config)
+      : null;
+
+    if (options.verbose) {
+      console.log('  Input:  ', inputPath);
+      console.log('  Output: ', outputPath);
+      if (configPath) console.log('  Config: ', configPath);
+      console.log('');
+    }
+
+    const result = await apidocly.generate({
+      input: inputPath,
+      output: outputPath,
+      config: configPath,
+      includePrivate: options.private,
+      singleFile: options.singleFile,
+      verbose: options.verbose
+    });
+
+    console.log(`  Done! Generated documentation for ${result.endpoints} endpoints.`);
+    console.log(`  Output: ${outputPath}\n`);
+  } catch (error) {
+    console.error('  Error:', error.message);
+    if (options.verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+run();

package/lib/generator/data-builder.js

@@ -0,0 +1,170 @@
+function buildApiData(endpoints, config, options = {}) {
+  const { includePrivate } = options;
+
+  let filteredEndpoints = endpoints;
+  if (!includePrivate) {
+    filteredEndpoints = endpoints.filter(ep => !ep.private);
+  }
+
+  // Don't filter by version here - frontend will handle version filtering
+  // This allows users to switch between endpoint versions in the UI
+
+  const groups = {};
+
+  for (const endpoint of filteredEndpoints) {
+    const groupName = endpoint.group || 'Default';
+
+    if (!groups[groupName]) {
+      groups[groupName] = {
+        name: groupName,
+        endpoints: []
+      };
+    }
+
+    groups[groupName].endpoints.push({
+      id: generateId(endpoint),
+      method: endpoint.method,
+      path: endpoint.path,
+      title: endpoint.title || endpoint.name || `${endpoint.method} ${endpoint.path}`,
+      name: endpoint.name || generateName(endpoint),
+      version: endpoint.version,
+      description: endpoint.description,
+      permission: endpoint.permission,
+      deprecated: endpoint.deprecated,
+      deprecatedText: endpoint.deprecatedText,
+      sampleRequest: endpoint.sampleRequest,
+      parameters: groupParams(endpoint.params),
+      query: groupParams(endpoint.query),
+      body: groupParams(endpoint.body),
+      headers: groupParams(endpoint.headers),
+      success: groupResponses(endpoint.success),
+      error: groupResponses(endpoint.error),
+      examples: endpoint.examples,
+      successExamples: endpoint.successExamples,
+      errorExamples: endpoint.errorExamples,
+      paramExamples: endpoint.paramExamples,
+      headerExamples: endpoint.headerExamples
+    });
+  }
+
+  const sortedGroups = Object.values(groups).sort((a, b) =>
+    a.name.localeCompare(b.name)
+  );
+
+  for (const group of sortedGroups) {
+    group.endpoints.sort((a, b) => {
+      const methodOrder = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+      const aOrder = methodOrder.indexOf(a.method);
+      const bOrder = methodOrder.indexOf(b.method);
+      if (aOrder !== bOrder) return aOrder - bOrder;
+      return a.path.localeCompare(b.path);
+    });
+  }
+
+  return {
+    project: {
+      name: config.name,
+      version: config.version,
+      description: config.description,
+      title: config.title,
+      url: config.url,
+      sampleUrl: config.sampleUrl,
+      environments: config.environments || []
+    },
+    header: config.header,
+    footer: config.footer,
+    groups: sortedGroups,
+    template: config.template,
+    generator: {
+      name: 'apidocly',
+      time: new Date().toISOString()
+    }
+  };
+}
+
+function generateId(endpoint) {
+  const name = endpoint.name || generateName(endpoint);
+  return name.toLowerCase().replace(/[^a-z0-9]/g, '-');
+}
+
+function generateName(endpoint) {
+  const method = endpoint.method.charAt(0) + endpoint.method.slice(1).toLowerCase();
+  const path = endpoint.path
+    .replace(/[/:{}]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '');
+  return `${method}${path.charAt(0).toUpperCase()}${path.slice(1)}`;
+}
+
+function groupParams(params) {
+  const grouped = {};
+
+  for (const param of params) {
+    const groupName = param.group || 'Parameter';
+    if (!grouped[groupName]) {
+      grouped[groupName] = [];
+    }
+    grouped[groupName].push(param);
+  }
+
+  return grouped;
+}
+
+function groupResponses(responses) {
+  const grouped = {};
+
+  for (const response of responses) {
+    const groupName = response.group || 'Response';
+    if (!grouped[groupName]) {
+      grouped[groupName] = [];
+    }
+    grouped[groupName].push(response);
+  }
+
+  return grouped;
+}
+
+function filterLatestVersions(endpoints) {
+  // Group endpoints by their unique key (method + normalized path + name)
+  const endpointMap = new Map();
+
+  for (const endpoint of endpoints) {
+    // Create a unique key based on method, path pattern, and name
+    // Normalize the path by removing version prefix (e.g., /1.0.0/, /1.0.1/)
+    const normalizedPath = endpoint.path.replace(/^\/\d+\.\d+\.\d+/, '');
+    const key = `${endpoint.method}:${normalizedPath}:${endpoint.name || ''}`;
+
+    const existingEndpoint = endpointMap.get(key);
+
+    if (!existingEndpoint) {
+      endpointMap.set(key, endpoint);
+    } else {
+      // Compare versions and keep the higher one
+      const existingVersion = existingEndpoint.version || '0.0.0';
+      const newVersion = endpoint.version || '0.0.0';
+
+      if (compareVersions(newVersion, existingVersion) > 0) {
+        endpointMap.set(key, endpoint);
+      }
+    }
+  }
+
+  return Array.from(endpointMap.values());
+}
+
+function compareVersions(v1, v2) {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const num1 = parts1[i] || 0;
+    const num2 = parts2[i] || 0;
+
+    if (num1 > num2) return 1;
+    if (num1 < num2) return -1;
+  }
+
+  return 0;
+}
+
+module.exports = { buildApiData };