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