add router prefix

.env.example

@@ -0,0 +1 @@
+ROUTE_PREFIX=/api/v1

.prettierrc

@@ -1,4 +1,6 @@
 {
-  "singleQuote": true,
-  "trailingComma": "all"
-}
+  "trailingComma": "all",
+  "printWidth": 120,
+  "semi": true,
+  "singleQuote": true
+}

README.md

@@ -1,3 +1,60 @@
 # koa-ts-demo
 
 Demo of Koa with TypeScript
+
+## Usage
+
+Start with development mode:
+
+```bash
+pnpm run start:dev
+```
+
+Start with production mode:
+
+```bash
+pnpm run start:prod
+```
+
+Format code:
+
+```bash
+pnpm run format
+```
+
+Lint code:
+
+```bash
+pnpm run lint
+```
+
+Build code:
+
+```bash
+pnpm run build
+```
+
+## Router
+
+How to add a new router (e.g. `/users`):
+
+1. Create a new file `usersController.ts` in `src/users/` folder. (e.g.`src/users/UsersController.ts`)
+2. Add a new router in `usersController.ts` file with `@Route('users')` decorator.
+3. Add a new class `UsersController` in `usesrsController` folder extends `Controller` class from `tsoa` package.
+4. Use `@Get()` decorator to add a new GET method or use `@Post()` decorator to add a new POST method, etc.
+
+## Swagger
+
+The swagger.json file is generated by `tsoa` package. The swagger UI is served by `koa2-swagger-ui` package.
+How to generate swagger.json:
+
+```bash
+pnpm run build:swagger
+```
+
+The development mode will auto generate `swagger.json` and `routes.ts` automatically so you don't need to run this command.
+This command will generate `swagger.json` file in `tsoa/swagger` folder and `routes.ts` file in `tsoa/routes` folder. Please and these two files to `.gitignore` file and **DO NOT** commit them to git.
+
+The `swagger.json` file is used by swagger UI to generate the swagger UI page. The `routes.ts` file is used by `@koa/router` in Koa.
+
+If you want to show the swagger UI page, please visit `http://localhost:8080/api/v1` in your browser.

package.json

@@ -14,7 +14,8 @@
     "start:dev": "concurrently \"nodemon\" \"nodemon -x tsoa spec-and-routes\"",
     "start:prod": "tsc && node dist/app.js",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-    "build": "tsoa spec-and-routes && tsc"
+    "build": "tsoa spec-and-routes && tsc",
+    "build:swagger": "tsoa spec-and-routes"
   },
   "dependencies": {
     "@koa/cors": "^4.0.0",
@@ -37,8 +38,8 @@
     "@types/koa__router": "^12.0.0",
     "@types/node": "^20.5.7",
     "@types/nodemon": "^1.19.2",
-    "@typescript-eslint/eslint-plugin": "^6.4.1",
-    "@typescript-eslint/parser": "^6.4.1",
+    "@typescript-eslint/eslint-plugin": "^6.5.0",
+    "@typescript-eslint/parser": "^6.5.0",
     "concurrently": "^8.2.1",
     "eslint": "^8.48.0",
     "eslint-config-prettier": "^9.0.0",

src/app.ts

@@ -3,22 +3,24 @@ import Koa from 'koa';
 import bodyParser from 'koa-bodyparser';
 import cors from '@koa/cors';
 import mount from 'koa-mount';
+import path from 'path';
 import serve from 'koa-static';
 import { koaSwagger } from 'koa2-swagger-ui';
 import router from './routes/main';
 
 const app: Koa = new Koa();
 const port: number = Number(process.env.PORT) || 8080;
+const routePrefix: string = process.env.ROUTE_PREFIX || '/';
 
 app
   .use(bodyParser())
   .use(cors())
-  .use(mount('/api/v1', serve('tsoa/swagger')))
+  .use(mount(routePrefix, serve('tsoa/swagger')))
   .use(
     koaSwagger({
-      routePrefix: '/api/v1',
+      routePrefix: routePrefix,
       swaggerOptions: {
-        url: '/api/v1/swagger.json',
+        url: path.join(routePrefix, 'swagger.json'),
       },
     }),
   )

src/routes/main.ts

@@ -2,7 +2,7 @@ import Router from '@koa/router';
 import { RegisterRoutes } from '../../tsoa/routes/routes';
 
 const router: Router = new Router({
-  prefix: '/api/v1',
+  prefix: process.env.ROUTE_PREFIX || '',
 });
 
 RegisterRoutes(router);

src/users/user.ts

@@ -1,4 +1,7 @@
 export interface User {
+  /**
+   * @isLong ErrorMessage
+   */
   id: number;
   email: string;
   name: string;