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
- Programmatic Schema Generation
- 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
- 🧰 Programmatic Schema Generation: Generate schema directly from code

Setup

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

Usage

Add the generator to your schema.prisma file:

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

Then run Prisma generate:

`bash
npx prisma generate
`

This will create OpenAPI documentation in the specified output directory.

Examples

$3

`prisma
// 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:


`yaml
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
`

$3

Generate a schema programmatically from a Prisma schema string:

`ts
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);
`

$3

`prisma
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
}
`

$3

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.

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

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

`javascript
/**
* @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
*/
`

$3

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

`prisma
/// 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:

`yaml
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