A Beginner's Guide to Implementing API Documentation with Swagger (with Prisma Integration)

[... Previous content remains the same up to the "Using TypeScript Schemas in Swagger Documentation" section ...]

Using Prisma Schema in Swagger Documentation

If you're using Prisma, you already have a well-defined schema for your database models. We can leverage this schema to generate TypeScript types and use them in our Swagger documentation. Here's how to do it:

First, make sure you have your Prisma schema defined in prisma/schema.prisma. For example:

// prisma/schema.prisma
 
model User {
  id    Int     @id @default(autoincrement())
  name  String
  email String  @unique
  age   Int?
}

Generate Prisma client and TypeScript types:

npx prisma generate

This command generates TypeScript types based on your Prisma schema.

Install @prisma/client if you haven't already:

npm install @prisma/client

Create a file to export Prisma-generated types. Let's call it src/models/prismaTypes.ts:

// src/models/prismaTypes.ts
 
import { Prisma } from "@prisma/client";
 
export type User = Prisma.UserGetPayload<{}>;
export type CreateUserInput = Prisma.UserCreateInput;

Now, we'll need to install a package that helps convert TypeScript to JSON Schema:

npm install typescript-json-schema

Add a script to your package.json to generate JSON schemas:

"scripts": {
  "generate-schemas": "typescript-json-schema ./src/models/prismaTypes.ts '*' --out ./src/schemas.json"
}

Run this script to generate the JSON schemas:

npm run generate-schemas

Update your Swagger configuration in swagger.ts:

import swaggerJsdoc from "swagger-jsdoc";
import schemas from "./schemas.json";
 
const options = {
  definition: {
    openapi: "3.0.0",
    info: {
      title: "My API",
      version: "1.0.0",
      description: "A sample API using Prisma and Swagger",
    },
    servers: [
      {
        url: "http://localhost:3000",
        description: "Development server",
      },
    ],
    components: {
      schemas: schemas,
    },
  },
  apis: ["./src/routes/*.ts"],
};
 
export const specs = swaggerJsdoc(options);

Update your route documentation to use these schemas:

// src/routes/userRoutes.ts
 
import express from "express";
import {
  createUser,
  getUsers,
  getUserById,
} from "../controllers/userController";
 
const router = express.Router();
 
/**
 * @swagger
 * /api/users:
 *   post:
 *     summary: Create a new user
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/CreateUserInput'
 *     responses:
 *       201:
 *         description: Created
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 */
router.post("/users", createUser);
 
/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: Retrieve a list of users
 *     responses:
 *       200:
 *         description: A list of users.
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
router.get("/users", getUsers);
 
/**
 * @swagger
 * /api/users/{id}:
 *   get:
 *     summary: Get a user by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: A single user.
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       404:
 *         description: User not found.
 */
router.get("/users/:id", getUserById);
 
export default router;

By following these steps, you're now using your Prisma schema to generate TypeScript types, which are then used to create JSON schemas for your Swagger documentation. This approach has several benefits:

Your API documentation will always be in sync with your database schema.
You can make changes to your Prisma schema and have them reflected in both your code and your documentation.
It provides a single source of truth for your data models.
You get the benefits of Prisma's powerful ORM along with comprehensive API documentation.

Remember to run the generate-schemas script whenever you make changes to your Prisma schema to keep your documentation up to date.

[... Rest of the content remains the same ...]

Building and Publishing a CLI as an npm Package Medical App Guide