@necessarylion/adonis-autoswagger 0.0.1 → 0.0.3

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

@@ -279,22 +279,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: {},
@@ -675,10 +676,12 @@ class AutoSwagger {
             }
             let schema = {
                 type: "object",
-                required: parsed.required,
                 properties: parsed.props,
                 description: name + " (Model)",
             };
+            if (parsed.required.length > 0) {
+                schema['required'] = parsed.required;
+            }
             models[name] = schema;
         }
         return models;

package/dist/parsers.d.ts

@@ -52,7 +52,17 @@ 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;
+        enum?: any;
+        pattern?: string;
+        example?: any;
+    };
 }
 export declare class InterfaceParser {
     exampleGenerator: ExampleGenerator;

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;
@@ -688,7 +688,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,54 +779,84 @@ class ValidatorParser {
     }
     parseSchema(json, refs) {
         const obj = {};
+        const required = [];
         for (const p of json["properties"]) {
-            let meta = {};
-            for (const v of p["validations"]) {
-                if (refs[v["ruleFnId"]].options?.example) {
-                    meta = { ...meta, example: refs[v["ruleFnId"]].options.example };
-                }
-                if (refs[v["ruleFnId"]].options?.min) {
-                    meta = { ...meta, minimum: refs[v["ruleFnId"]].options.min };
-                }
-                if (refs[v["ruleFnId"]].options?.max) {
-                    meta = { ...meta, maximum: refs[v["ruleFnId"]].options.max };
-                }
-                if (refs[v["ruleFnId"]].options?.choices) {
-                    meta = { ...meta, choices: refs[v["ruleFnId"]].options.choices };
-                }
-                if (refs[v["ruleFnId"]].options?.toString().includes("/")) {
-                    meta = { ...meta, pattern: refs[v["ruleFnId"]].options.toString() };
-                }
-            }
+            let meta = this.getMetaFromValidations(p["validations"], refs);
             // console.dir(p, { depth: null });
             // console.dir(validations, { depth: null });
             // console.log(min, max, choices, regex);
-            obj[p["fieldName"]] =
-                p["type"] === "object"
-                    ? { type: "object", properties: this.parseSchema(p, refs) }
-                    : p["type"] === "array"
-                        ? {
+            const type = p["type"];
+            const field = p["fieldName"];
+            if (type === "object") {
+                console.log(field, p);
+                obj[field] = { type: "object", ...this.parseSchema(p, refs) };
+            }
+            else {
+                // if array
+                if (type === "array") {
+                    if (p["each"]["type"] === "object") {
+                        obj[field] = {
                             type: "array",
-                            items: p["each"]["type"] === "object"
-                                ? {
-                                    type: "object",
-                                    properties: this.parseSchema(p["each"], refs),
-                                }
-                                : {
-                                    type: "number",
-                                    example: meta.example ?? meta.minimum ?? this.exampleGenerator.exampleByType("number"),
-                                    ...meta,
-                                },
-                        }
-                        : {
-                            type: "number",
-                            example: meta.example ?? meta.minimum ?? this.exampleGenerator.exampleByType("number"),
-                            ...meta,
+                            items: {
+                                type: "object",
+                                ...this.parseSchema(p["each"], refs),
+                            }
+                        };
+                    }
+                    else {
+                        const meta = this.getMetaFromValidations(p["each"]["validations"], refs);
+                        obj[field] = {
+                            type: "array",
+                            items: {
+                                type: this.getType(p["each"]["type"]),
+                                ...meta,
+                                example: meta.example ?? meta.minimum ?? this.exampleGenerator.exampleByType("number"),
+                            },
                         };
+                    }
+                }
+                else {
+                    obj[field] = {
+                        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 = {};
+        for (const v of validations) {
+            if (refs[v["ruleFnId"]].options?.example) {
+                meta = { ...meta, example: refs[v["ruleFnId"]].options.example };
+            }
+            if (refs[v["ruleFnId"]].options?.min) {
+                meta = { ...meta, minimum: refs[v["ruleFnId"]].options.min };
+            }
+            if (refs[v["ruleFnId"]].options?.max) {
+                meta = { ...meta, maximum: refs[v["ruleFnId"]].options.max };
+            }
+            if (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() };
+            }
+        }
+        return meta;
     }
 }
 exports.ValidatorParser = ValidatorParser;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@necessarylion/adonis-autoswagger",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Auto-Generate swagger docs for AdonisJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",