@necessarylion/adonis-autoswagger 0.0.2 → 0.0.4

package/README.md

@@ -13,11 +13,13 @@ Adonis AutoSwagger <br />
 ## 💻️ Install
 
 ```bash
-pnpm i adonis-autoswagger #using pnpm
+pnpm i @necessarylion/adonis-autoswagger #using pnpm
 ```
 
 ---
 
+*This is a fork of [adonis-autoswagger](https://github.com/ad-on-is/adonis-autoswagger) with some additional features.*
+
 ## ⭐️ Features
 
 - Creates **paths** automatically based on `routes.ts`
@@ -76,7 +78,7 @@ In your `routes.ts`
 ## 6️⃣ for AdonisJS v6
 
 ```js
-import AutoSwagger from "adonis-autoswagger";
+import AutoSwagger from "@necessarylion/adonis-autoswagger";
 import swagger from "#config/swagger";
 // returns swagger in YAML
 router.get("/swagger", async () => {
@@ -94,7 +96,7 @@ router.get("/docs", async () => {
 ## 5️⃣ for AdonisJS v5
 
 ```js
-import AutoSwagger from "adonis-autoswagger";
+import AutoSwagger from "@necessarylion/adonis-autoswagger";
 import swagger from "Config/swagger";
 // returns swagger in YAML
 Route.get("/swagger", async () => {
@@ -456,6 +458,71 @@ Generates responses and requestBody based on your simple Controller-Annotation (
 
 ## Schemas
 
+### Validators
+
+Automatically generates swagger schema-descriptions based on your validators.
+
+#### Adding example values
+
+```ts
+export const adminLogin = vine.compile(
+  vine.object({
+    email: vine.string().trim().example('admin@laconcept.de'),
+    password: vine.string().trim().example('password'),
+  })
+)
+```
+
+##### Create custom validators with vine
+
+```ts
+// start/validators/example.ts
+
+import vine, { VineNumber, VineString, VineNativeEnum } from '@vinejs/vine'
+import { EnumLike } from '@vinejs/vine/types'
+
+type Options = {
+  example: any
+}
+
+declare module '@vinejs/vine' {
+  interface VineString {
+    example(example: string): this
+  }
+  interface VineNumber {
+    example(example: number): this
+  }
+  interface VineNativeEnum<Values extends EnumLike> {
+    example(example: string): this
+  }
+}
+
+export const exampleRule = vine.createRule((_: unknown, opt: Options) => {
+  return opt.example
+})
+
+VineString.macro('example', function (this: VineString, example: string) {
+  return this.use(exampleRule({ example }))
+})
+VineNumber.macro('example', function (this: VineNumber, example: number) {
+  return this.use(exampleRule({ example }))
+})
+VineNativeEnum.macro('example', function (this: VineNativeEnum<any>, example: string) {
+  return this.use(exampleRule({ example }))
+})
+```
+
+##### Import in `adonisrc.ts` preloads
+
+```ts
+preloads: [
+  () => import('#start/routes'),
+  () => import('#start/kernel'),
+  () => import('#start/sentry'),
+  () => import('#start/validators/example.ts'),
+],
+```
+
 ### Models
 
 Automatically generates swagger schema-descriptions based on your models
@@ -464,7 +531,16 @@ Automatically generates swagger schema-descriptions based on your models
 
 ### Interfaces
 
-Instead of using `param: any` you can now use custom interfaces `param: UserDetails`. The interfaces files need to be located at `app/Interfaces/`
+Instead of using `param: any` you can now use custom interfaces `param: UserDetails`. The interfaces files need to be located at `app/Interfaces/` or `app/interfaces/`
+
+```ts
+export interface UserDetails {
+  // @example(John Doe)
+  name: string;
+  // @example(johndoe@example.com)
+  email: string;
+}
+```
 
 ### Enums
 

package/dist/autoswagger.js

@@ -41,9 +41,10 @@ const json_to_pretty_yaml_1 = __importDefault(require("json-to-pretty-yaml"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const util_1 = __importDefault(require("util"));
+const lodash_1 = require("lodash");
 const http_status_code_1 = __importDefault(require("http-status-code"));
-const lodash_1 = __importDefault(require("lodash"));
-const lodash_2 = require("lodash");
+const lodash_2 = __importDefault(require("lodash"));
+const lodash_3 = require("lodash");
 const fs_2 = require("fs");
 const scalarCustomCss_1 = require("./scalarCustomCss");
 const adonishelpers_1 = require("./adonishelpers");
@@ -279,22 +280,23 @@ class AutoSwagger {
                         description: "The resource has been created",
                     },
                 },
-                securitySchemes: {
-                    BearerAuth: {
-                        type: "http",
-                        scheme: "bearer",
-                    },
-                    BasicAuth: {
-                        type: "http",
-                        scheme: "basic",
-                    },
-                    ApiKeyAuth: {
-                        type: "apiKey",
-                        in: "header",
-                        name: "X-API-Key",
+                securitySchemes: this.options.securitySchemes
+                    ? this.options.securitySchemes
+                    : {
+                        BearerAuth: {
+                            type: "http",
+                            scheme: "bearer",
+                        },
+                        BasicAuth: {
+                            type: "http",
+                            scheme: "basic",
+                        },
+                        ApiKeyAuth: {
+                            type: "apiKey",
+                            in: "header",
+                            name: "X-API-Key",
+                        },
                     },
-                    ...this.options.securitySchemes,
-                },
                 schemas: this.schemas,
             },
             paths: {},
@@ -355,10 +357,9 @@ class AutoSwagger {
                     return;
                 globalTags.push({
                     name: tag,
-                    description: "Everything related to " + tag,
                 });
             });
-            const { sourceFile, action, customAnnotations, operationId } = await this.getDataBasedOnAdonisVersion(route);
+            let { sourceFile, action, customAnnotations, operationId } = await this.getDataBasedOnAdonisVersion(route);
             route.methods.forEach((method) => {
                 let responses = {};
                 if (method === "HEAD")
@@ -397,12 +398,11 @@ class AutoSwagger {
                 parameters = (0, helpers_1.mergeParams)(parameters, actionParams);
                 if (tag != "") {
                     globalTags.push({
-                        name: tag.toUpperCase(),
-                        description: "Everything related to " + tag.toUpperCase(),
+                        name: tag.toUpperCase()
                     });
                     tags = [tag.toUpperCase()];
                 }
-                if ((0, lodash_2.isEmpty)(responses)) {
+                if ((0, lodash_3.isEmpty)(responses)) {
                     responses[responseCodes[method]] = {
                         description: http_status_code_1.default.getMessage(responseCodes[method]),
                         content: {
@@ -453,9 +453,10 @@ class AutoSwagger {
                             break;
                     }
                 }
+                action = (0, lodash_1.startCase)(action);
                 const sf = sourceFile.split("/").at(-1).replace(".ts", "");
                 let m = {
-                    summary: `${summary}${action !== "" ? ` (${action})` : "route"}`,
+                    summary: `${summary}${action !== "" ? ` ${action}` : "route"}`,
                     description: description + "\n\n _" + sourceFile + "_ - **" + action + "**",
                     operationId: operationId,
                     parameters: parameters,
@@ -477,7 +478,7 @@ class AutoSwagger {
             });
         }
         // filter unused tags
-        const usedTags = lodash_1.default.uniq(Object.entries(paths)
+        const usedTags = lodash_2.default.uniq(Object.entries(paths)
             .map(([p, val]) => Object.entries(val)[0][1].tags)
             .flat());
         docs.tags = globalTags.filter((tag) => usedTags.includes(tag.name));
@@ -496,7 +497,7 @@ class AutoSwagger {
                 sourceFile = route.meta.resolvedHandler.namespace;
                 action = route.meta.resolvedHandler.method;
                 // If not defined by an annotation, use the combination of "controllerNameMethodName"
-                if (action !== "" && (0, lodash_2.isUndefined)(operationId) && route.handler) {
+                if (action !== "" && (0, lodash_3.isUndefined)(operationId) && route.handler) {
                     operationId = (0, helpers_1.formatOperationId)(route.handler);
                 }
             }
@@ -547,7 +548,7 @@ class AutoSwagger {
         if (this.options.debug) {
             if (sourceFile !== "") {
                 console.log(typeof customAnnotations !== "undefined" &&
-                    !lodash_1.default.isEmpty(customAnnotations)
+                    !lodash_2.default.isEmpty(customAnnotations)
                     ? `\x1b[32m✓ FOUND for ${action}\x1b[0m`
                     : `\x1b[33m✗ MISSING for ${action}\x1b[0m`, `${sourceFile} (${route.methods[0].toUpperCase()} ${route.pattern})`);
             }
@@ -675,10 +676,14 @@ class AutoSwagger {
             }
             let schema = {
                 type: "object",
-                required: parsed.required,
                 properties: parsed.props,
                 description: name + " (Model)",
             };
+            if (parsed.required.length > 0) {
+                schema['required'] = parsed.required;
+            }
+            if (name.toLowerCase().includes('readme.md'))
+                continue;
             models[name] = schema;
         }
         return models;

package/dist/example.js

@@ -262,6 +262,8 @@ class ExampleGenerator {
                 return this.exampleByField("date");
             case "object":
                 return {};
+            case "uuid":
+                return this.exampleByField("uuid");
             default:
                 return null;
         }
@@ -292,6 +294,7 @@ class ExampleGenerator {
             price: 10.5,
             avatar: "https://example.com/avatar.png",
             url: "https://example.com",
+            uuid: "2b0bf725-d404-481f-b431-17f1182a5e57"
         };
         if (typeof ex[field] !== "undefined") {
             return ex[field];

package/dist/parsers.d.ts

@@ -52,11 +52,14 @@ export declare class ValidatorParser {
     validatorToObject(validator: VineValidator<any, any>): Promise<any>;
     parsePropsAndMeta(obj: any, testObj: any, validator: VineValidator<any, any>): Promise<any>;
     objToTest(obj: any): {};
-    parseSchema(json: any, refs: any): {};
+    parseSchema(json: any, refs: any): {
+        properties: {};
+    };
+    getType(type: string): string;
     getMetaFromValidations(validations: any, refs: any): {
         minimum?: number;
         maximum?: number;
-        choices?: any;
+        enum?: any;
         pattern?: string;
         example?: any;
     };

package/dist/parsers.js

@@ -110,7 +110,7 @@ class CommentParser {
             return h;
         }
         if (line.startsWith("@paramPath")) {
-            required = false;
+            required = true;
         }
         if (line.startsWith("@paramQuery")) {
             required = false;
@@ -621,6 +621,11 @@ class ModelParser {
                 type = "string";
                 format = "date";
             }
+            if (type === "uuid") {
+                indicator = "type";
+                type = "string";
+                format = "uuid";
+            }
             if (field === "email") {
                 indicator = "type";
                 type = "string";
@@ -688,7 +693,7 @@ class ValidatorParser {
         // console.dir(json, { depth: null });
         const obj = {
             type: "object",
-            properties: this.parseSchema(validator.toJSON()["schema"]["schema"], validator.toJSON()["refs"]),
+            ...this.parseSchema(validator.toJSON()["schema"]["schema"], validator.toJSON()["refs"]),
         };
         // console.dir(obj, { depth: null });
         const testObj = this.objToTest(obj["properties"]);
@@ -779,6 +784,7 @@ class ValidatorParser {
     }
     parseSchema(json, refs) {
         const obj = {};
+        const required = [];
         for (const p of json["properties"]) {
             let meta = this.getMetaFromValidations(p["validations"], refs);
             // console.dir(p, { depth: null });
@@ -788,7 +794,7 @@ class ValidatorParser {
             const field = p["fieldName"];
             if (type === "object") {
                 console.log(field, p);
-                obj[field] = { type: "object", properties: this.parseSchema(p, refs) };
+                obj[field] = { type: "object", ...this.parseSchema(p, refs) };
             }
             else {
                 // if array
@@ -798,7 +804,7 @@ class ValidatorParser {
                             type: "array",
                             items: {
                                 type: "object",
-                                properties: this.parseSchema(p["each"], refs),
+                                ...this.parseSchema(p["each"], refs),
                             }
                         };
                     }
@@ -807,7 +813,7 @@ class ValidatorParser {
                         obj[field] = {
                             type: "array",
                             items: {
-                                type: "number",
+                                type: this.getType(p["each"]["type"]),
                                 ...meta,
                                 example: meta.example ?? meta.minimum ?? this.exampleGenerator.exampleByType("number"),
                             },
@@ -816,16 +822,25 @@ class ValidatorParser {
                 }
                 else {
                     obj[field] = {
-                        type: "number",
+                        type: this.getType(type),
                         example: meta.example ?? meta.minimum ?? this.exampleGenerator.exampleByType("number"),
                         ...meta,
                     };
                 }
             }
             if (!p["isOptional"])
-                obj[p["fieldName"]]["required"] = true;
+                required.push(p["fieldName"]);
         }
-        return obj;
+        const res = { properties: obj };
+        if (required.length > 0)
+            res["required"] = required;
+        return res;
+    }
+    getType(type) {
+        if (type == 'literal') {
+            return 'string';
+        }
+        return type;
     }
     getMetaFromValidations(validations, refs) {
         let meta = {};
@@ -840,7 +855,7 @@ class ValidatorParser {
                 meta = { ...meta, maximum: refs[v["ruleFnId"]].options.max };
             }
             if (refs[v["ruleFnId"]].options?.choices) {
-                meta = { ...meta, choices: refs[v["ruleFnId"]].options.choices };
+                meta = { ...meta, enum: refs[v["ruleFnId"]].options.choices };
             }
             if (refs[v["ruleFnId"]].options?.toString().includes("/")) {
                 meta = { ...meta, pattern: refs[v["ruleFnId"]].options.toString() };

package/dist/scalarCustomCss.d.ts

@@ -1 +1 @@
-export declare const scalarCustomCss = "\n/* basic theme */\n.light-mode {\n  --theme-background-1: #fff;\n  --theme-background-2: #fafaf9;\n  --theme-background-3: rgb(245 245 245);\n\n  --theme-color-1: #21201c;\n  --theme-color-2: #63635d;\n  --theme-color-3: #8e8e8e;\n\n  --theme-color-accent: #5a45ff;\n  --theme-background-accent: #5a45ff1f;\n\n  --theme-border-color: color(display-p3 0.913 0.912 0.903);\n  --theme-code-language-color-supersede: var(--theme-color-1);\n  --theme-code-languages-background-supersede: var(--theme-background-3);\n}\n.dark-mode {\n  --theme-background-1: #0f0f0f;\n  --theme-background-2: #222222;\n  --theme-background-3: #272727;\n\n  --theme-color-1: #e2e4e8;\n  --theme-color-2: rgba(255, 255, 255, 0.62);\n  --theme-color-3: #6a737d;\n\n  --theme-color-accent: #e2ddfe;\n  --theme-background-accent: #3c2d6a;\n\n  --theme-border-color: rgba(255, 255, 255, 0.1);\n  --theme-code-language-color-supersede: var(--theme-color-1);\n  --theme-code-languages-background-supersede: var(--theme-background-3);\n}\n\n/* Document Sidebar */\n.light-mode .t-doc__sidebar,\n.dark-mode .t-doc__sidebar {\n  --sidebar-background-1: var(--theme-background-1);\n  --sidebar-color-1: var(--theme-color-1);\n  --sidebar-color-2: var(--theme-color-2);\n  --sidebar-border-color: var(--theme-border-color);\n\n  --sidebar-item-hover-background: var(--theme-background-2);\n  --sidebar-item-hover-color: currentColor;\n\n  --sidebar-item-active-background: var(--theme-background-accent);\n  --sidebar-color-active: var(--theme-color-accent);\n\n  --sidebar-search-background: var(--theme-background-2);\n  --sidebar-search-color: var(--theme-color-3);\n  --sidebar-search-border-color: var(--theme-border-color);\n}\n\n/* advanced */\n.light-mode {\n  --theme-color-green: #0e766e;\n  --theme-color-red: #e53935;\n  --theme-color-yellow: #e2931d;\n  --theme-color-blue: #0f766e;\n  --theme-color-orange: #f76d47;\n  --theme-color-purple: #4338ca;\n}\n.dark-mode {\n  --theme-color-green: #0ad8b6;\n  --theme-color-red: #e5484d;\n  --theme-color-yellow: #eac063;\n  --theme-color-blue: #6abaff;\n  --theme-color-orange: #ff9b52;\n  --theme-color-purple: #6550b9;\n}\n/* custom-theme */\n.show-api-client-button:before {\n  background: white !important;\n}\n.show-api-client-button span,\n.show-api-client-button svg {\n  color: var(--theme-background-1) !important;\n}\n.section:not(:last-of-type),\n.section-container {\n  border-top: none !important;\n  border-bottom: none !important;\n}\n.section-container:after,\n.tag-section-container section.section:after {\n  content: \"\";\n  width: 100%;\n  height: 1px;\n  position: absolute;\n  top: 0;\n  left: 0;\n  background: repeating-linear-gradient(\n    90deg,\n    var(--theme-border-color) 0 4px,\n    transparent 0 8px\n  );\n}\n.section-container:nth-of-type(2):after {\n  display: none;\n}\n.tag-section-container .section:first-of-type:after {\n  display: none;\n}\n.sidebar {\n  border-right: none !important;\n}\n.t-doc__sidebar {\n  position: relative;\n}\n.t-doc__sidebar:after {\n  content: \"\";\n  width: 1px;\n  height: 100%;\n  position: absolute;\n  right: 0;\n  top: 0;\n  background: repeating-linear-gradient(\n    0deg,\n    var(--theme-border-color) 0 4px,\n    transparent 0 8px\n  );\n  display: block;\n}\n.download-cta .download-button,\n.scalar-api-reference .section .markdown a {\n  --theme-color-accent: var(--theme-color-1) !important;\n  text-decoration: underline !important;\n  cursor: pointer;\n}";
+export declare const scalarCustomCss = "\n/* basic theme */\n.light-mode {\n  --theme-background-1: #fff;\n  --theme-background-2: #fafaf9;\n  --theme-background-3: rgb(245 245 245);\n\n  --theme-color-1: #21201c;\n  --theme-color-2: #63635d;\n  --theme-color-3: #8e8e8e;\n\n  --theme-color-accent: #5a45ff;\n  --theme-background-accent: #5a45ff1f;\n\n  --theme-border-color: color(display-p3 0.913 0.912 0.903);\n  --theme-code-language-color-supersede: var(--theme-color-1);\n  --theme-code-languages-background-supersede: var(--theme-background-3);\n}\n.dark-mode {\n  --theme-background-1: #0f0f0f;\n  --theme-background-2: #222222;\n  --theme-background-3: #272727;\n\n  --theme-color-1: #e2e4e8;\n  --theme-color-2: rgba(255, 255, 255, 0.62);\n  --theme-color-3: #6a737d;\n\n  --theme-color-accent: #e2ddfe;\n  --theme-background-accent: #3c2d6a;\n\n  --theme-border-color: rgba(255, 255, 255, 0.1);\n  --theme-code-language-color-supersede: var(--theme-color-1);\n  --theme-code-languages-background-supersede: var(--theme-background-3);\n}\n\n/* Document Sidebar */\n.light-mode .t-doc__sidebar,\n.dark-mode .t-doc__sidebar {\n  --sidebar-background-1: var(--theme-background-1);\n  --sidebar-color-1: var(--theme-color-1);\n  --sidebar-color-2: var(--theme-color-2);\n  --sidebar-border-color: var(--theme-border-color);\n\n  --sidebar-item-hover-background: var(--theme-background-2);\n  --sidebar-item-hover-color: currentColor;\n\n  --sidebar-item-active-background: var(--theme-background-accent);\n  --sidebar-color-active: var(--theme-color-accent);\n\n  --sidebar-search-background: var(--theme-background-2);\n  --sidebar-search-color: var(--theme-color-3);\n  --sidebar-search-border-color: var(--theme-border-color);\n}\n\n/* advanced */\n.light-mode {\n  --theme-color-green: #0e766e;\n  --theme-color-red: #e53935;\n  --theme-color-yellow: #e2931d;\n  --theme-color-blue: #0f766e;\n  --theme-color-orange: #f76d47;\n  --theme-color-purple: #4338ca;\n}\n.dark-mode {\n  --theme-color-green: #0ad8b6;\n  --theme-color-red: #e5484d;\n  --theme-color-yellow: #eac063;\n  --theme-color-blue: #6abaff;\n  --theme-color-orange: #ff9b52;\n  --theme-color-purple: #6550b9;\n}\n/* custom-theme */\n.show-api-client-button:before {\n  background: white !important;\n}\n.show-api-client-button span,\n.show-api-client-button svg {\n  color: var(--theme-background-1) !important;\n}\n.section:not(:last-of-type),\n.section-container {\n  border-top: none !important;\n  border-bottom: none !important;\n}\n.section-container:after,\n.tag-section-container section.section:after {\n  content: \"\";\n  width: 100%;\n  height: 1px;\n  position: absolute;\n  top: 0;\n  left: 0;\n  background: repeating-linear-gradient(\n    90deg,\n    var(--theme-border-color) 0 4px,\n    transparent 0 8px\n  );\n}\n.section-container:nth-of-type(2):after {\n  display: none;\n}\n.tag-section-container .section:first-of-type:after {\n  display: none;\n}\n.sidebar {\n  border-right: none !important;\n}\n.t-doc__sidebar {\n  position: relative;\n}\n.t-doc__sidebar:after {\n  content: \"\";\n  width: 1px;\n  height: 100%;\n  position: absolute;\n  right: 0;\n  top: 0;\n  background: repeating-linear-gradient(\n    0deg,\n    var(--theme-border-color) 0 4px,\n    transparent 0 8px\n  );\n  display: block;\n}\n.download-cta .download-button,\n.scalar-api-reference .section .markdown a {\n  --theme-color-accent: var(--theme-color-1) !important;\n  text-decoration: underline !important;\n  cursor: pointer;\n}\n.sidebar-heading-link[tabindex=\"-1\"] .sidebar-heading-link-title {\n  font-weight: bold !important;\n  font-family: monospace;\n  text-transform: uppercase;\n}\n.scalar .scalar-app-layout {\n  max-width: 95% !important;\n  box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px !important;\n}\n.scalar-container {\n  background: #434343d4 !important; \n}\n";

package/dist/scalarCustomCss.js

@@ -130,4 +130,17 @@ exports.scalarCustomCss = `
   --theme-color-accent: var(--theme-color-1) !important;
   text-decoration: underline !important;
   cursor: pointer;
-}`;
+}
+.sidebar-heading-link[tabindex="-1"] .sidebar-heading-link-title {
+  font-weight: bold !important;
+  font-family: monospace;
+  text-transform: uppercase;
+}
+.scalar .scalar-app-layout {
+  max-width: 95% !important;
+  box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px !important;
+}
+.scalar-container {
+  background: #434343d4 !important; 
+}
+`;

package/dist/types.js

@@ -9,6 +9,7 @@ exports.standardTypes = [
     "date",
     "boolean",
     "any",
+    "uuid",
 ]
     .map((type) => [type, type + "[]"])
     .flat();

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@necessarylion/adonis-autoswagger",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Auto-Generate swagger docs for AdonisJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "watchexec -e ts -- tsc",
+    "build": "tsc",
+    "prepare": "npm run build"
+  },
   "author": "Adis Durakovic <adis.durakovic@gmail.com>",
   "repository": {
     "type": "git",
@@ -38,10 +44,5 @@
     "bracketSpacing": true,
     "arrowParens": "always"
   },
-  "packageManager": "pnpm@8.11.0",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "dev": "watchexec -e ts -- tsc",
-    "build": "tsc"
-  }
-}
+  "packageManager": "pnpm@8.11.0"
+}