feat: with swagger docs

Author: tomanagle

package.json

@@ -22,6 +22,8 @@
     "pino-pretty": "^7.1.0",
     "prom-client": "^14.0.0",
     "response-time": "^2.3.2",
+    "swagger-jsdoc": "^6.1.0",
+    "swagger-ui-express": "^4.1.6",
     "zod": "^3.9.8"
   },
   "devDependencies": {
@@ -36,6 +38,8 @@
     "@types/node": "^16.11.1",
     "@types/pino": "^6.3.11",
     "@types/response-time": "^2.3.5",
+    "@types/swagger-jsdoc": "^6.0.1",
+    "@types/swagger-ui-express": "^4.1.3",
     "ts-node-dev": "^1.1.8",
     "typescript": "^4.4.4"
   }

src/app.ts

@@ -6,6 +6,7 @@ import logger from "./utils/logger";
 import routes from "./routes";
 import deserializeUser from "./middleware/deserializeUser";
 import { restResponseTimeHistogram, startMetricsServer } from "./utils/metrics";
+import swaggerDocs from "./utils/swagger";
 
 const port = config.get<number>("port");
 
@@ -38,4 +39,6 @@ app.listen(port, async () => {
   routes(app);
 
   startMetricsServer();
+
+  swaggerDocs(app, port);
 });

src/routes.ts

@@ -23,8 +23,44 @@ import { createSessionSchema } from "./schema/session.schema";
 import { createUserSchema } from "./schema/user.schema";
 
 function routes(app: Express) {
+  /**
+   * @openapi
+   * /healthcheck:
+   *  get:
+   *     tags:
+   *     - Healthcheck
+   *     description: Responds if the app is up and running
+   *     responses:
+   *       200:
+   *         description: App is up and running
+   */
   app.get("/healthcheck", (req: Request, res: Response) => res.sendStatus(200));
 
+  /**
+   * @openapi
+   * '/api/users':
+   *  post:
+   *     tags:
+   *     - User
+   *     summary: Register a user
+   *     requestBody:
+   *      required: true
+   *      content:
+   *        application/json:
+   *           schema:
+   *              $ref: '#/components/schemas/CreateUserInput'
+   *     responses:
+   *      200:
+   *        description: Success
+   *        content:
+   *          application/json:
+   *            schema:
+   *              $ref: '#/components/schemas/CreateUserResponse'
+   *      409:
+   *        description: Conflict
+   *      400:
+   *        description: Bad request
+   */
   app.post("/api/users", validateResource(createUserSchema), createUserHandler);
 
   app.post(
@@ -43,6 +79,28 @@ function routes(app: Express) {
     createProductHandler
   );
 
+  /**
+   * @openapi
+   * '/api/products/{productId}':
+   *  get:
+   *     tags:
+   *     - Products
+   *     summary: Get a single product by the productId
+   *     parameters:
+   *      - name: productId
+   *        in: path
+   *        description: The id of the product
+   *        required: true
+   *     responses:
+   *       200:
+   *         description: Success
+   *         content:
+   *          application/json:
+   *           schema:
+   *              $ref: '#/components/schema/Product'
+   *       404:
+   *         description: Product not found
+   */
   app.put(
     "/api/products/:productId",
     [requireUser, validateResource(updateProductSchema)],

src/schema/product.schema.ts

@@ -1,4 +1,27 @@
 import { object, number, string, TypeOf } from "zod";
+
+/**
+ * @openapi
+ * components:
+ *   schema:
+ *     Product:
+ *       type: object
+ *       required:
+ *        - title
+ *        - description
+ *        - price
+ *        - image
+ *       properties:
+ *         title:
+ *           type: string
+ *         description:
+ *           type: string
+ *         price:
+ *           type: number
+ *         image:
+ *           type: string
+ */
+
 const payload = {
   body: object({
     title: string({

src/schema/user.schema.ts

@@ -1,5 +1,44 @@
 import { object, string, TypeOf } from "zod";
 
+/**
+ * @openapi
+ * components:
+ *  schemas:
+ *    CreateUserInput:
+ *      type: object
+ *      required:
+ *        - email
+ *        - name
+ *        - password
+ *        - passwordConfirmation
+ *      properties:
+ *        email:
+ *          type: string
+ *          default: jane.doe@example.com
+ *        name:
+ *          type: string
+ *          default: Jane Doe
+ *        password:
+ *          type: string
+ *          default: stringPassword123
+ *        passwordConfirmation:
+ *          type: string
+ *          default: stringPassword123
+ *    CreateUserResponse:
+ *      type: object
+ *      properties:
+ *        email:
+ *          type: string
+ *        name:
+ *          type: string
+ *        _id:
+ *          type: string
+ *        createdAt:
+ *          type: string
+ *        updatedAt:
+ *          type: string
+ */
+
 export const createUserSchema = object({
   body: object({
     name: string({

src/utils/swagger.ts

@@ -0,0 +1,47 @@
+import { Express, Request, Response } from "express";
+import swaggerJsdoc from "swagger-jsdoc";
+import swaggerUi from "swagger-ui-express";
+import { version } from "../../package.json";
+import log from "./logger";
+
+const options: swaggerJsdoc.Options = {
+  definition: {
+    openapi: "3.0.0",
+    info: {
+      title: "REST API Docs",
+      version,
+    },
+    components: {
+      securitySchemas: {
+        bearerAuth: {
+          type: "http",
+          scheme: "bearer",
+          bearerFormat: "JWT",
+        },
+      },
+    },
+    security: [
+      {
+        bearerAuth: [],
+      },
+    ],
+  },
+  apis: ["./src/routes.ts", "./src/schema/*.ts"],
+};
+
+const swaggerSpec = swaggerJsdoc(options);
+
+function swaggerDocs(app: Express, port: number) {
+  // Swagger page
+  app.use("/docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+
+  // Docs in JSON format
+  app.get("/docs.json", (req: Request, res: Response) => {
+    res.setHeader("Content-Type", "application/json");
+    res.send(swaggerSpec);
+  });
+
+  log.info(`Docs available at http://localhost:${port}/docs`);
+}
+
+export default swaggerDocs;

tsconfig.json

@@ -33,7 +33,7 @@
     // "typeRoots": [],                                  /* Specify multiple folders that act like `./node_modules/@types`. */
     // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
     // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
-    // "resolveJsonModule": true,                        /* Enable importing .json files */
+    "resolveJsonModule": true /* Enable importing .json files */,
     // "noResolve": true,                                /* Disallow `import`s, `require`s or `<reference>`s from expanding the number of files TypeScript should add to a project. */
 
     /* JavaScript Support */