Prisma OpenAPI

Generate OpenAPI schema from Prisma models

A Prisma generator that automatically creates OpenAPI specifications from your Prisma schema. Seamlessly integrate your database models with API documentation without writing any additional code.

• Features
• Setup
• Usage
• Examples
  • Basic Usage
  • Custom Configuration
  • JSDoc Integration
  • Prisma Comments as Descriptions
• Configuration
• License

Features

• 🔄 Automatic Generation: Convert Prisma models to OpenAPI schemas with a single command
• 🔍 Type Safety: Maintain type consistency between your database and API documentation
• 🛠️ Customizable: Configure which models to include and set API metadata
• 🧩 Relationship Support: Properly maps Prisma relationships to OpenAPI references
• *️⃣ Enum Support: Full support for Prisma enums in your API documentation
• 📝 JSDoc Generation: Create JSDoc comments for your TypeScript types based on the Prisma schema

Setup

npm i -D prisma-openapi
pnpm add -D prisma-openapi
yarn add -D prisma-openapi

Usage

Add the generator to your schema.prisma file:

generator openapi {
  provider = "prisma-openapi"
  output   = "./openapi"
}

Then run Prisma generate:

npx prisma generate

This will create OpenAPI documentation in the specified output directory.

Examples

Basic Usage

// schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

generator openapi {
  provider = "prisma-openapi"
  output   = "./openapi"
}

/// Represents a user in the system
model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  posts     Post[]
}

/// Represents a blog post
model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int
}

Running prisma generate will create OpenAPI specifications for these models:

openapi: 3.1.0
info:
  title: Prisma API
  description: API generated from Prisma schema
  version: 1.0.0
components:
  schemas:
    User:
      type: object
      description: Represents a user in the system
      properties:
        id:
          type: integer
          format: int32
        email:
          type: string
        name:
          type: string
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
      required:
        - id
        - email
    Post:
      type: object
      description: Represents a blog post
      properties:
        id:
          type: integer
          format: int32
        title:
          type: string
        content:
          type: string
        published:
          type: boolean
        author:
          $ref: '#/components/schemas/User'
        authorId:
          type: integer
          format: int32
      required:
        - id
        - title
        - published
        - author
        - authorId

Custom Configuration

generator openapi {
  provider      = "prisma-openapi"
  output        = "./openapi"
  title         = "My API"
  description   = "API for my application"
  includeModels = "User,Post"
  excludeModels = "Passwords"
  generateYaml  = true
  generateJson  = false
  generateJsDoc = false
}

JSDoc Integration

When generateJsDoc is enabled, prisma-openapi will generate a JavaScript file containing OpenAPI-compatible JSDoc comments. This can be integrated with tools like swagger-jsdoc to combine your API route documentation with your Prisma model definitions.

generator openapi {
  provider      = "prisma-openapi"
  output        = "./openapi"
  generateJsDoc = true
}

The generated JSDoc comments can be imported into your API documentation workflow:

/**
 * @openapi
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 *         email:
 *           type: string
 *         name:
 *           type: string
 *         posts:
 *           type: array
 *           items:
 *             $ref: '#/components/schemas/Post'
 *       required:
 *         - id
 *         - email
 */

Prisma Comments as Descriptions

Prisma-openapi automatically converts Prisma schema comments into OpenAPI description fields. Use triple-slash comments (///) to add descriptions to your models and fields:

/// User account information
model User {
  /// Primary key for the user
  id    Int    @id @default(autoincrement())
  /// User's email address for login
  email String @unique
  /// Optional display name
  name  String?
}

This will generate:

User:
  type: object
  description: User account information
  properties:
    id:
      type: integer
      description: Primary key for the user
    email:
      type: string
      description: User's email address for login
    name:
      type: string
      description: Optional display name

Configuration

Option	Description	Default
output	Output directory for OpenAPI schema	./openapi
title	API title in OpenAPI spec	"Prisma API"
description	API description in OpenAPI spec	Empty string
includeModels	Comma-separated list of models to include	All models
excludeModels	Comma-separated list of models to exclude	None
generateYaml	Generate YAML format	true
generateJson	Generate JSON format	false
generateJsDoc	Include JSDoc comments in the schema	false

License

MIT