ldap-rest 0.3.0 → 0.3.1

package/dist/src/plugins/twake/james.d.ts

@@ -5,6 +5,53 @@ import type { DM } from '../../bin';
 import type { AttributeValue } from '../../lib/ldapActions';
 import { Hooks } from '../../hooks';
 import type { ChangesToNotify } from '../ldap/onChange';
+/**
+ * OpenAPI schemas specific to the James integration.
+ *
+ * @openapi-component
+ * JamesQuotaUsage:
+ *   type: object
+ *   description: |
+ *     Quota information for a mailbox user as returned by the James
+ *     WebAdmin API (`GET /quota/users/{mail}`). Contains separate
+ *     counters for message count and storage size.
+ *   properties:
+ *     count:
+ *       type: object
+ *       description: Message-count quota.
+ *       properties:
+ *         used:
+ *           type: integer
+ *           description: Number of messages currently stored.
+ *           example: 142
+ *         max:
+ *           type: integer
+ *           nullable: true
+ *           description: |
+ *             Maximum number of messages allowed. `null` means unlimited.
+ *           example: 10000
+ *     size:
+ *       type: object
+ *       description: Storage-size quota (bytes).
+ *       properties:
+ *         used:
+ *           type: integer
+ *           description: Bytes currently used.
+ *           example: 524288000
+ *         max:
+ *           type: integer
+ *           nullable: true
+ *           description: |
+ *             Maximum bytes allowed. `null` means unlimited.
+ *           example: 2147483648
+ *   example:
+ *     count:
+ *       used: 142
+ *       max: 10000
+ *     size:
+ *       used: 524288000
+ *       max: 2147483648
+ */
 export default class James extends TwakePlugin {
     name: string;
     roles: Role[];

package/docs/plugin-development/README.md

@@ -13,6 +13,7 @@ This guide will help you create powerful, production-ready plugins for LDAP-Rest
 - [Configuration Best Practices](#configuration-best-practices)
 - [Complete Plugin Example](#complete-plugin-example)
 - [Testing Your Plugin](#testing-your-plugin)
+- [Documenting REST endpoints (OpenAPI)](./openapi.md)
 
 ---
 
@@ -1282,7 +1283,7 @@ source ~/.test-env && npm run test:dev
 ## Additional Resources
 
 - [Contributing Guide](../../CONTRIBUTING.md) - Git workflow and PR guidelines
-- [Hooks Reference](../../HOOKS.md) - Complete list of available hooks
+- [Hooks Reference](./hooks.md) - Complete list of available hooks
 - [Core Plugin Examples](../../src/plugins/) - Browse existing plugins
 - [Test Examples](../../test/plugins/) - See how core plugins are tested
 

package/docs/plugin-development/openapi.md

@@ -0,0 +1,144 @@
+# Documenting plugin endpoints (OpenAPI)
+
+The published API reference at <https://linagora.github.io/ldap-rest/api/> is
+generated from `openapi.json`, which itself is built statically by
+[`scripts/generate-openapi.ts`](../../scripts/generate-openapi.ts) — it walks
+every plugin's `api()` method and reads the JSDoc comments above each route.
+
+You don't need to touch the generator to enrich your plugin's documentation.
+Two JSDoc directives drive the entire pipeline:
+
+- `@openapi` — placed **just above an `app.method(path, handler)` call**,
+  describes that single route.
+- `@openapi-component` — placed anywhere in the file, registers reusable
+  schemas under `components.schemas` so multiple routes can `$ref` them.
+
+Both directives carry inline **YAML** that follows the
+[OpenAPI 3.0 Operation Object](https://spec.openapis.org/oas/v3.0.3#operation-object)
+(or [Schema Object](https://spec.openapis.org/oas/v3.0.3#schema-object) for
+components). The generator parses the YAML and merges it on top of the
+defaults it would have emitted, so you only describe what you want to enrich.
+
+## Per-route metadata: `@openapi`
+
+```ts
+/**
+ * @openapi
+ * summary: Get group by CN
+ * description: |
+ *   The `:cn` segment may be either the group's RDN value or its full DN.
+ *   Returns the raw LDAP entry.
+ * responses:
+ *   '200':
+ *     description: Group entry.
+ *     content:
+ *       application/json:
+ *         schema: { $ref: '#/components/schemas/Group' }
+ *         example:
+ *           dn: cn=admins,ou=groups,dc=example,dc=com
+ *           cn: admins
+ *           description: Server administrators
+ *   '404':
+ *     description: Group not found.
+ */
+app.get(`${this.config.api_prefix}/v1/ldap/groups/:cn`, asyncHandler(...));
+```
+
+Anything below the `@openapi` line (up to the next `@directive` or the end of
+the JSDoc block) is YAML. The keys you provide override the auto-generated
+ones; everything you omit keeps the generator's defaults.
+
+### What you can override
+
+Any field of an OpenAPI Operation Object, including:
+
+| Field         | Notes                                                                            |
+| ------------- | -------------------------------------------------------------------------------- |
+| `summary`     | Short, one-line title.                                                           |
+| `description` | Long description (markdown).                                                     |
+| `tags`        | Array of strings; defaults to the plugin's tag.                                  |
+| `parameters`  | Concatenated with auto-generated path params (your entries win on duplicates).   |
+| `requestBody` | Replace the generic `application/json` placeholder with a real schema + example. |
+| `responses`   | Replace per status code.                                                         |
+| `security`    | List of security requirement objects (works as-is).                              |
+| `deprecated`  | `true` to mark the operation as deprecated.                                      |
+| `operationId` | Stable identifier for code generators.                                           |
+
+### What is autodetected
+
+The generator already extracts:
+
+- the **HTTP method** (`get`, `post`, …) from the call expression;
+- the **path** (substituting local `const prefix = ...` variables, the
+  `${this.config.api_prefix}` template, and a few well-known config knobs);
+- **path parameters** from `:param` segments;
+- a default **summary** built from the verb and the last path segment;
+- the plugin's **tag** (configured in `pluginTags` in the generator).
+
+So a minimal, correct `@openapi` block is often only two or three keys.
+
+## Reusable schemas: `@openapi-component`
+
+Place this anywhere in your plugin file (the convention is right above the
+class). The body is a YAML map of `<SchemaName>: <SchemaDefinition>` pairs:
+
+```ts
+/**
+ * @openapi-component
+ * Group:
+ *   type: object
+ *   required: [dn, cn]
+ *   properties:
+ *     dn: { type: string, example: cn=admins,ou=groups,dc=example,dc=com }
+ *     cn: { type: string, example: admins }
+ *     member:
+ *       type: array
+ *       items: { type: string }
+ * Error:
+ *   type: object
+ *   properties:
+ *     error: { type: string }
+ *     code: { type: integer }
+ */
+export default class LdapGroups extends DmPlugin {
+  // ...
+}
+```
+
+Refer to them from any route using `$ref`:
+
+```yaml
+schema: { $ref: '#/components/schemas/Group' }
+```
+
+Component names are global to the spec, so prefix them with the plugin's
+domain (`Group`, `ScimUser`, `PasswordPolicy`) to avoid collisions.
+
+## Tips
+
+- **Examples beat specs.** A single concrete `example:` block is worth a
+  dozen `description:` lines for someone trying the API for the first time.
+- **YAML alignment.** The generator strips the leading `*` from each line
+  before parsing, then dedents the block, so you can use any consistent
+  indentation as long as it's even within the block.
+- **Multiline strings.** Use YAML block scalars (`description: |`) for
+  paragraphs and code samples — they round-trip cleanly through Redoc.
+- **Annotation is opt-in.** Routes without an `@openapi` block are
+  **excluded** from the published spec — the generator prints a
+  `⚠️  Skipping undocumented route` warning so the author notices, but
+  the route does not surface in Redoc. The published doc therefore
+  reflects intentionally-documented API surface only, not every Express
+  call we happened to find.
+- **A plugin with zero annotated routes disappears entirely** from the
+  spec, by the same rule.
+
+## Regenerate locally
+
+```sh
+npm run generate:openapi   # writes openapi.json
+npm run build:pages        # rebuilds the static site under _site/
+```
+
+Open `_site/api/index.html` to preview the Redoc rendering. The published
+site at <https://linagora.github.io/ldap-rest/api/> is rebuilt automatically
+on every `v*` tag push.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -120,6 +120,10 @@
       "types": "./dist/src/plugins/ldap/organization.d.ts",
       "import": "./dist/plugins/ldap/organization.js"
     },
+    "./plugin-ldap-organizations": {
+      "types": "./dist/src/plugins/ldap/organizations.d.ts",
+      "import": "./dist/plugins/ldap/organizations.js"
+    },
     "./plugin-ldap-passwordpolicy": {
       "types": "./dist/src/plugins/ldap/passwordPolicy.d.ts",
       "import": "./dist/plugins/ldap/passwordPolicy.js"
@@ -552,6 +556,7 @@
     "build:dev": "./.dev.mk builddev",
     "build:docker": "./.dev.mk builddocker",
     "build:dockerfile": "./.dev.mk Dockerfile",
+    "build:pages": "tsx scripts/build-pages.ts",
     "build:prod": "npm run clean && NODE_ENV=production rollup -c && npm run build:browser && node scripts/moveBrowserLibs.mjs && npm run build:dockerfile",
     "build:watch": "rollup -c --watch",
     "check": "npm run check:ts && npm run lint && npm run format:check",
@@ -598,6 +603,7 @@
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/chai": "^5.2.2",
     "@types/express": "^5.0.3",
+    "@types/js-yaml": "^4.0.9",
     "@types/mocha": "^10.0.10",
     "@types/multer": "^2.0.0",
     "@types/node": "^24.5.1",
@@ -611,6 +617,7 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^5.5.4",
     "fast-glob": "^3.3.3",
+    "js-yaml": "^4.1.1",
     "mocha": "^11.7.2",
     "nock": "^14.0.10",
     "prettier": "^3.6.2",