Improve code splitting and architecture

Author: kerwanp

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 dist
 node_modules
+coverage
 
 packages/openapi-typescript/test/fixtures/cli-outputs/out
 

docs/.vitepress/en.ts

@@ -78,6 +78,16 @@ export const en = defineConfig({
             { text: "About", link: "/openapi-react-query/about" },
           ],
         },
+        {
+          text: "openapi-adonis",
+          items: [
+            { text: "Getting Started", link: "/openapi-adonis/" },
+            { text: "useQuery", link: "/openapi-react-query/use-query" },
+            { text: "useMutation", link: "/openapi-react-query/use-mutation" },
+            { text: "useSuspenseQuery", link: "/openapi-react-query/use-suspense-query" },
+            { text: "About", link: "/openapi-react-query/about" },
+          ],
+        },
       ],
     },
     search: {

docs/data/contributors.json

@@ -0,0 +1,70 @@
+---
+title: openapi-adonis
+---
+
+# Introduction
+
+openapi-adonis is an [Adonis.js] library to automatically generate OpenAPI schemas and documentation.
+
+- ✅ Creates operations from the Adonis Router
+- ✅ Automatically adds your models to the schemas
+- ✅ Automatically adds your `@vinejs/vine` validators to the schemas
+- ✅ Extended type-inference using Typescript metadata
+- ✅ Extensible using Typescript decorators
+- ✅ Generates documentation for **Swagger, Scalar, Rapidoc**
+
+The library is inspired by the popular library [@nestjs/swagger](https://www.npmjs.com/package/@nestjs/swagger) and is built on top of [openapi-decorators](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-decorators).
+
+::: code-group
+
+```tsx [app/controllers/users_controller.ts]
+import { apiOperation, apiResponse } from "openapi-adonis/decorators";
+import User from "#models/user";
+
+class UsersController {
+  @apiOperation({ summary: "List users" })
+  @apiResponse({ type: [User] })
+  async list() {
+    return User.findManyBy({});
+  }
+}
+```
+
+```tsx [app/models/user.ts]
+import { apiProperty } from "openapi-adonis/decorators";
+
+class User {
+  @apiProperty()
+  declare id: number;
+
+  @apiProperty()
+  declare name: string;
+
+  @apiProperty({ required: false })
+  declare mobile?: string;
+}
+```
+
+```tsx [start/routes.ts]
+import router from "@adonisjs/core/services/router";
+import AdonisOpenAPI from "openapi-adonis";
+
+const UsersController = () => import("#controllers/users_controller");
+
+router.post("/users", [UsersController, "create"]);
+
+const builder = AdonisOpenAPI.document().setTitle("OpenAPI Adonis Example");
+AdonisOpenAPI.setup("/docs", router, builder);
+```
+
+:::
+
+## Setup
+
+Install this library by using `ace`:
+
+```bash
+node ace add openapi-adonis
+```
+
+## Basic usage

docs/openapi-adonis/index.md

@@ -2,7 +2,7 @@
   "$schema": "https://biomejs.dev/schemas/1.8.1/schema.json",
   "extends": ["../../biome.json"],
   "files": {
-    "ignore": ["./example/"]
+    "ignore": ["./example/", "./coverage/"]
   },
   "linter": {
     "rules": {

packages/openapi-adonis/biome.json

@@ -1,18 +1,21 @@
-import User from '#models/user'
-import { apiBody, apiOperation, apiResponse, apiParam, apiQuery } from 'openapi-adonis/decorators'
+import User from "#models/user";
+import { listUserValidator } from "#validators/user";
+import { apiBody, apiOperation, apiParam, apiQuery, apiResponse } from "openapi-adonis/decorators";
+import { VineType, ModelType } from "openapi-adonis";
 
 export default class UsersController {
-  @apiOperation({ summary: 'Get users', tags: ['User'] })
-  @apiResponse({ type: User })
-  @apiParam({ name: 'id' })
-  @apiQuery({ name: 'query' })
+  @apiOperation({ summary: "Get users" })
+  @apiResponse({ type: ModelType(User) })
+  @apiParam({ name: "id" })
+  @apiQuery({ name: "query" })
+  @apiBody({ type: VineType(listUserValidator, "listUserValidator") })
   async index(): Promise<User> {
-    return new User()
+    return new User();
   }
 
-  @apiOperation({ summary: 'Create new user', tags: ['User'] })
-  @apiBody({ type: User })
+  @apiOperation({ summary: "Create new user" })
+  // @apiBody({ type: User })
   async create(): Promise<User> {
-    return new User()
+    return new User();
   }
 }

packages/openapi-adonis/example/app/controllers/users_controller.ts

@@ -0,0 +1,12 @@
+import vine from "@vinejs/vine";
+
+export const listUserValidator = vine.compile(
+  vine.object({
+    one: vine.string(),
+    two: vine.number(),
+    nested: vine.object({
+      test: vine.number(),
+    }),
+    array: vine.array(vine.number()).maxLength(5),
+  }),
+);

packages/openapi-adonis/example/app/validators/user.ts

@@ -7,19 +7,20 @@
 |
 */
 
-import router from '@adonisjs/core/services/router'
-import AdonisOpenAPI from 'openapi-adonis'
+import router from "@adonisjs/core/services/router";
+import AdonisOpenAPI from "openapi-adonis";
 
-const UsersController = () => import('#controllers/users_controller')
+const UsersController = () => import("#controllers/users_controller");
 
-router.get('/', async () => {
+router.get("/", async () => {
   return {
-    hello: 'world',
-  }
-})
+    hello: "world",
+  };
+});
 
-router.get('/users/:id', [UsersController, 'index'])
-router.post('/users', [UsersController, 'create'])
+// router.get("/users/:id", [UsersController, "index"]);
+// router.post("/users", [UsersController, "create"]);
+router.resource("users", UsersController).apiOnly();
 
-const builder = AdonisOpenAPI.document().setTitle('OpenAPI Adonis Example')
-AdonisOpenAPI.setup('/docs', router, builder)
+const builder = AdonisOpenAPI.document().setTitle("OpenAPI Adonis Example");
+AdonisOpenAPI.setup("/docs", router, builder);

packages/openapi-adonis/example/start/routes.ts

@@ -45,6 +45,7 @@
     "format": "biome format . --write",
     "lint": "biome check .",
     "test": "vitest run",
+    "coverage": "vitest run --coverage",
     "version": "pnpm run prepare && pnpm run build"
   },
   "dependencies": {
@@ -60,6 +61,7 @@
     "@adonisjs/http-server": "^7.2.3",
     "@types/lodash": "^4.17.7",
     "@types/node": "^22.1.0",
+    "@vitest/coverage-v8": "^2.0.5",
     "tsup": "^8.2.4",
     "typescript": "^5.4.5",
     "unplugin-swc": "^1.5.1"

packages/openapi-adonis/package.json

@@ -4,11 +4,15 @@ import type { Router } from "@adonisjs/http-server";
 import { DocumentBuilder } from "openapi-decorators/builders";
 import { generateScalarUI } from "openapi-decorators/ui";
 import { loadRouter } from "./loaders/loadRouter";
+import { VineTypeResolver } from "./resolvers/vine-type.resolver";
+
+export { VineType } from "./resolvers/vine-type.resolver";
+export { ModelType } from "openapi-decorators/resolvers";
 
 // biome-ignore lint/complexity/noStaticOnlyClass: TODO: move out of class
 export default class AdonisOpenAPI {
   public static document() {
-    return new DocumentBuilder();
+    return new DocumentBuilder().addResolver(VineTypeResolver);
   }
 
   public static async load(builder: DocumentBuilder, router: Router): Promise<OpenAPIV3.Document> {

packages/openapi-adonis/src/index.ts

@@ -1,39 +1,33 @@
 import type { OpenAPIV3 } from "openapi-types";
 import { OperationBuilder, type DocumentBuilder } from "openapi-decorators/builders";
 import type { AdonisRoute } from "../types";
-import { loadController } from "./loadController";
-import { getApiTags } from "openapi-decorators";
-import { loadApiTags } from "openapi-decorators/loaders";
+import { loadApiOperation, loadController } from "openapi-decorators/loaders";
 import { normalizeRoutePattern } from "../utils/normalizeRoutePattern";
 
 export async function loadRoute(document: DocumentBuilder, route: AdonisRoute) {
   if (typeof route.handler !== "object" || !Array.isArray(route.handler.reference)) {
     return;
   }
 
-  const importer = route.handler.reference[0] as Function;
+  const importer = route.handler.reference[0] as () => Promise<{ default: any }>;
   const propertyKey = route.handler.reference[1] as string;
 
   const target = (await importer().then((t: any) => t.default)) as any;
 
-  const operation = new OperationBuilder();
-
-  const apiTags = getApiTags(target);
-  if (apiTags) {
-    loadApiTags(operation, apiTags);
-  }
-
-  loadController(document, operation, target.prototype, propertyKey);
-
   for (const method of route.methods) {
     if (method === "HEAD") {
       continue;
     }
 
-    document.setOperation(
-      method.toLowerCase() as OpenAPIV3.HttpMethods,
-      normalizeRoutePattern(route.pattern),
-      operation.build(),
-    );
+    const operation = new OperationBuilder();
+
+    loadApiOperation(operation, {
+      method: method.toLowerCase() as `${OpenAPIV3.HttpMethods}`,
+      pattern: normalizeRoutePattern(route.pattern),
+    });
+
+    loadController(document, operation, target.prototype, propertyKey);
+
+    document.addOperation(operation);
   }
 }