prisma-openapi

Prisma OpenAPI

Generate OpenAPI schema from Prisma models

Demo 🚀

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
  • Programmatic Schema Generation
  • Custom Configuration
  • JSDoc Integration
  • Prisma Comments as Descriptions
  • Field Exclusion
• 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
• 🧰 Programmatic Schema Generation: Generate schema directly from code

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"
}

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

Programmatic Schema Generation

Generate a schema programmatically from a Prisma schema string:

import { generateOpenApiSchema } from "prisma-openapi/lib";

const schema = `
datasource db {
  provider = "postgresql"
}

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  name  String?
}
`;

// Returns YAML by default
const yamlOutput = await generateOpenApiSchema(schema, {
  title: "My API",
  description: "Generated via SDK",
});

// Or generate JSON output
const jsonOutput = await generateOpenApiSchema(schema, {
  title: "My API",
  description: "Generated via SDK",
  generateYaml: false,
  generateJson: true,
});

console.log(yamlOutput);

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

Field Exclusion

You can exclude specific fields from the generated OpenAPI schema using two approaches:

1. Using @openapi.ignore in field comments:

Add @openapi.ignore to a field's triple-slash comment to exclude it from the generated schema:

model User {
  id       Int    @id @default(autoincrement())
  email    String @unique
  name     String?
  /// @openapi.ignore
  password String
}

2. Using excludeFields in generator config:

Specify fields to exclude using ModelName.fieldName format:

generator openapi {
  provider      = "prisma-openapi"
  output        = "./openapi"
  excludeFields = "User.password, User.secretKey"
}

Both approaches can be used together. A field is excluded if it matches either condition. Excluded fields are removed from both properties and required in the generated schema.

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
excludeFields	Comma-separated list of fields to exclude (ModelName.fieldName)	None
generateYaml	Generate YAML format	true
generateJson	Generate JSON format	false
generateJsDoc	Include JSDoc comments in the schema	false

License

MIT