pantharshit00 / prisma-docs-generator Goto Github PK

Prisma generator for automatically generating documentation reference from the Prisma schema.

License: MIT License

TypeScript 88.48% JavaScript 5.03% CSS 6.49%

prisma-generator prisma prisma2 code-generation html hacktoberfest

prisma-docs-generator's Introduction

Prisma Documentation Generator

Automatically generate a reference from your Prisma Schema. This package contains a prisma generator so reference will automatically update everytime you will run prisma generate

Getting Started

Install this package using:

npm install -D prisma-docs-generator

Add the generator to the schema

generator docs {
  provider = "node node_modules/prisma-docs-generator"
}

Run npx prisma generate to trigger the generator. This will create a docs folder in prisma/docs
Serve the docs using npx prisma-docs-generator serve

Options

Specifying Output

You can specify the out of the docs using the output property

generator docs {
  provider = "node node_modules/prisma-docs-generator"
  output = "../../docs"
}

includeRelationFields

You can specify whether relation fields are shown or not. Default value is true.

generator docs {
  provider = "node node_modules/prisma-docs-generator"
  includeRelationFields = false
}

CLI

This package also ships with a CLI which is used to serve the docs right now. It has the following subcommands:

`serve`

Serves the static html which the generator generated. It reads the output path from the prisma schema or it will use the default. Use --port or -p to change the port the express server uses.

License

MIT Harshit Pant

(This is not an official Prisma project. It is personally maintained by me )

prisma-docs-generator's People

Contributors

Stargazers

Watchers

prisma-docs-generator's Issues

Cannot read property 'map' of undefined with Prisma v2.15

I am getting this error when running npx prisma generate. I am using Prisma v2.15 and nativeTypes

Error: 
✔ Generated Prisma Client (2.15.0) to ./node_modules/@prisma/client in 3.69s

TypeError: Cannot read property 'map' of undefined
    at TOCGenerator.getTypes (/Users/akash/Documents/kaamwork/kaamwork-nest/node_modules/prisma-docs-generator/dist/generator/toc.js:84:47)
    at TOCGenerator.getData (/Users/akash/Documents/kaamwork/kaamwork-nest/node_modules/prisma-docs-generator/dist/generator/toc.js:94:25)
    at new TOCGenerator (/Users/akash/Documents/kaamwork/kaamwork-nest/node_modules/prisma-docs-generator/dist/generator/toc.js:5:26)
    at HTMLPrinter.toHTML (/Users/akash/Documents/kaamwork/kaamwork-nest/node_modules/prisma-docs-generator/dist/printer/index.js:47:24)
    at Object.onGenerate (/Users/akash/Documents/kaamwork/kaamwork-nest/node_modules/prisma-docs-generator/dist/index.js:49:101)
    at async LineStream.<anonymous> (/Users/akash/Documents/kaamwork/kaamwork-nest/node_modules/@prisma/generator-helper/dist/generatorHandler.js:13:32)

Use `indent-string` to indent the generated html

We can use indent-string to format the generated html

Generating OpenAPI/Swagger Specs

Can the prisma-docs-generator be used to generate Open API / Swagger Spec?
can it be enhanced?

@pantharshit00 - Would appreciate your inputs

Add a README.md

Must enable 'extendedIndexes` preview feature when trying to serve documents

It seems you are using a 3.x of Prisma, as it considers extendedIndexes a preview feature. I am using 4.x Prisma and this is no longer a preview feature.
Output of generating the prisma client and docs and then trying to serve:

nathan@Server-Box:~/dev/alliance/ams$ npx prisma generate
Environment variables loaded from .env
Prisma schema loaded from prisma/schema.prisma

✔ Generated Prisma Client (4.8.0 | library) to ./prisma/client in 1.08s

✔ Generated Prisma Docs Generator to ./prisma/docs in 568ms
You can now start using Prisma Client in your code. Reference: https://pris.ly/d/client

import { PrismaClient } from './prisma/client'
const prisma = new PrismaClient()


warn Versions of [email protected] and @prisma/[email protected] don't match.
This might lead to unexpected behavior.
Please make sure they have the same version.


nathan@Server-Box:~/dev/alliance/ams$ npx prisma-docs-generator serve
Error: Get DMMF: Schema parsing
error: Error parsing attribute "@@index": You must enable `extendedIndexes` preview feature to be able to define the index type.
  -->  schema.prisma:537
   | 
536 | 
537 |   @@index([id], type: Hash)
   | 
error: Error parsing attribute "@@index": You must enable `extendedIndexes` preview feature to be able to define the index type.
  -->  schema.prisma:538
   | 
537 |   @@index([id], type: Hash)
538 |   @@index([sid], type: Hash)
   | 

Validation Error Count: 2

Prisma CLI Version : 3.15.2
    at /home/nathan/dev/alliance/ams/node_modules/@prisma/sdk/dist/engine-commands/getDmmf.js:125:14
    at /home/nathan/dev/alliance/ams/node_modules/@prisma/sdk/node_modules/fp-ts/lib/Either.js:268:52
    at pipe (/home/nathan/dev/alliance/ams/node_modules/@prisma/sdk/node_modules/fp-ts/lib/function.js:288:23)
    at /home/nathan/dev/alliance/ams/node_modules/@prisma/sdk/dist/engine-commands/getDmmf.js:115:50
    at e.run (/home/nathan/dev/alliance/ams/node_modules/ts-pattern/dist/index.cjs:1:4927)
    at e.otherwise (/home/nathan/dev/alliance/ams/node_modules/ts-pattern/dist/index.cjs:1:4570)
    at getDmmfNodeAPI (/home/nathan/dev/alliance/ams/node_modules/@prisma/sdk/dist/engine-commands/getDmmf.js:128:6)
    at async getDMMF (/home/nathan/dev/alliance/ams/node_modules/@prisma/sdk/dist/engine-commands/getDmmf.js:53:16)
    at async getGenerators (/home/nathan/dev/alliance/ams/node_modules/@prisma/sdk/dist/get-generators/getGenerators.js:107:16)
    at async execute (/home/nathan/dev/alliance/ams/node_modules/prisma-docs-generator/dist/cli.js:68:26)

It may be wise to configure the CLI version used based on the project's Prisma version used, if possible.

Unknown arg `is` and `isNot`

Been using your docs generator for complex nested queries, and so far super helpful! Came across the following error.

My query

const users = await prisma.user.findMany({
  where: {
    participants: {
      some: {
        registrations: {
          some: {
            eventOption: {
              is: {
                eventId: req.body.eventId
              }
            }
          }
        }
      }
    }
  }
})

Your doc says for eventOption:

Terminal output:

Not sure how to query this. I want to find users who participate in events who have registered for event options of a particular event.

Add tests

// TODO: outline ideal testing solution and initial test cases
// Snapshot??
// jest-dom?

TypeError: mappings.filter is not a function

Hi!
I use prisma-docs-generator 0.0.6 and Prisma 2.11.0, has this error.

npx prisma generate
Environment variables loaded from /Users/tyshgc/development/tyshgc/study_prisma/starter/prisma/.env
Prisma schema loaded from prisma/schema.prisma
Error: 
TypeError: mappings.filter is not a function
    at getMappings (/Users/tyshgc/development/tyshgc/study_prisma/starter/node_modules/prisma-docs-generator/dist/generator/transformDMMF.js:17:10)
    at Object.transformDMMF [as default] (/Users/tyshgc/development/tyshgc/study_prisma/starter/node_modules/prisma-docs-generator/dist/generator/transformDMMF.js:11:19)
    at Object.onGenerate (/Users/tyshgc/development/tyshgc/study_prisma/starter/node_modules/prisma-docs-generator/dist/index.js:38:45)
    at LineStream.<anonymous> (/Users/tyshgc/development/tyshgc/study_prisma/starter/node_modules/@prisma/generator-helper/dist/generatorHandler.js:13:46)
    at LineStream.emit (events.js:314:20)
    at addChunk (_stream_readable.js:303:12)
    at readableAddChunk (_stream_readable.js:279:9)
    at LineStream.Readable.push (_stream_readable.js:218:10)
    at LineStream.Transform.push (_stream_transform.js:166:32)
    at LineStream._pushBuffer (/Users/tyshgc/development/tyshgc/study_prisma/starter/node_modules/@prisma/generator-helper/dist/byline.js:108:23)

In getMappings() of transformDMMF.ts, The argument mappings is an object, not an array?

Add enums to the docs

Right now prisma-docs-generator doesn't generator types for schema enums. It need to do so.

Pagination and groupping + mermaid diagram

In my case, when generate docs and open index.html, browser being shutted down due to too long contents.

I hope to separate each models to each page. Also, traveling third party libraries of prisma about ERD generation, none of them could express my database relationships cleary due to too many tables. Therefore, I hope to suggest you to providing groupping feature, and drawing mermaid diagram per each group page.

pages per models
support groupping
mermaid diagrams per each group

If you agree, then I can help you about the last feature, "mermaid diagrams per each group".

/// @group articles
model bbs_articles {
}

/// @group sales
model shopping_sales {
}

/// @group orders
model shopping_orders {
}

Docs should specify to be a dev dependency

In the instructions on installation, npm install prisma-docs-generator should be npm install -D prisma-docs-generator.

There is no need for this dependency to not be a dev dependency.

Add a generator option to enable html compression

Might be a good idea if someone wants to deploy this. This need a bit more exploration in terms of generation time and other related concerns.

"Self host" style generation

Right now we are generating the style from a template but ideally I should I should generate them from an output of a reference schema.

[FIXED] Do not define a valid '.' target

I am getting \AppData\Roaming\npm-cache_npx\16448\node_modules\prisma-docs-generator\node_modules\kleur' do not define a valid '.' target whenever I run npx prisma-docs-generator serve and during npx prisma generate

Prisma 2.4.1

TypeError: Cannot read property 'length' of undefined

Starting with prisma version 2.29.0 to current (2.30.0);
The following error now appears when generating docs:

TypeError: Cannot read property 'length' of undefined
    at ModelGenerator.getModelDirective (/api/node_modules/prisma-docs-generator/dist/generator/model.js:196:28)
    at /api/node_modules/prisma-docs-generator/dist/generator/model.js:522:34
    at Array.map (<anonymous>)
    at ModelGenerator.getModels (/api/node_modules/prisma-docs-generator/dist/generator/model.js:518:38)
    at ModelGenerator.getData (/api/node_modules/prisma-docs-generator/dist/generator/model.js:530:26)
    at new ModelGenerator (/api/node_modules/prisma-docs-generator/dist/generator/model.js:35:26)
    at HTMLPrinter.toHTML (/api/node_modules/prisma-docs-generator/dist/printer/index.js:48:26)
    at Object.onGenerate (/api/node_modules/prisma-docs-generator/dist/index.js:51:83)
    at async LineStream.<anonymous> (/api/node_modules/@prisma/generator-helper/dist/generatorHandler.js:33:24)

Reverting back to prisma version 2.28.0 the error no longer appears.

[feat] Summary of models at top

Hi @pantharshit00!

What do you think of adding a summary of all models at the top of page, with click-through links to each model?

We have a lot of models, so sometimes quite a bit of scrolling is needed to get to the relevant docs for a particular model.

Select property not included

I just tried this out and love the concept. However, for me the most important attribute of any prisma call - or at least the piece that winds up being most complicated and needing the most documentation - is "select", which is curiously left out of all the API examples. This is where, for example, counting and aggregation, or filtering relationships would occur. The types and property names for those attributes and collections would be super helpful information, I'm always asking myself if it's { select: { _count: { select: { subobject { select etc... etc... with this recursive structure for handling relationships.

Would be a great feature add to see this part of the API included too!

Add integrations tests

I found out that some paths are broken when using this with something like redwood.

Integration tests would be nice here.

Change `prisma.` to `db.`

hosting is not working [bug]

successfully installed and generated doc
After running npx prisma-docs-generator serve getting the following:

env: node\r: No such file or directory

After running node node_modules/prisma-docs-generator getting empty return, no printout - seems like its hanging. Nothing is at http://localhost:5858/.

Generated HTML has styling issue

This is what I get. Any help?

Can I use comments in `schema.prisma`

Is it possible use comments from schema.prisma in generated docs? For example when I will add comment to model or to a field.

@default([]) will crash the generator

First of all thanks for your amazing work! 🫶

Once you have time maybe you can take a look at the @default([]) attribute. The generator seems to crash for me everytime I am enabling it. This is the prisma Schema that I used:

model Person {
  id			String		@id @db.Uuid
  first_name	String		@db.VarChar(50)
  last_name		String		@db.VarChar(50)
  emails		String[]	@default([]) @db.VarChar(320)

  @@map("person")
}

Here is the error log from what Prisma outputted running pnpx prisma generate.

Error Log

> prisma generate

  prisma:engines  binaries to download libquery-engine, migration-engine +0ms
  prisma:loadEnv  project root found at ./package.json +0ms
  prisma:tryLoadEnv  Environment variables loaded from ./.env +0ms
Environment variables loaded from .env
Prisma schema loaded from prisma/schema.prisma
  prisma:getConfig  Using getConfig Wasm +0ms
  prisma:getConfig  config data retrieved without errors in getConfig Wasm +2ms
  prisma:getDMMF  Using getDmmf Wasm +0ms
  prisma:getDMMF  Using given datamodel +0ms
  prisma:getDMMF  dmmf data retrieved without errors in getDmmf Wasm +29ms
  prisma:generator  prismaCLIDir./node_modules/prisma +0ms
  prisma:generator  prismaClientDir ./node_modules/@prisma/client +0ms
  prisma:generator  baseDir ./prisma +0ms
  prisma:generator  typescriptPath ./node_modules/.pnpm/[email protected]/node_modules/typescript +1ms
  prisma:GeneratorProcess  2023-04-06T15:40:51.169Z prisma:client:generator  requiredEngine: libqueryEngine +0ms
  prisma:getGenerators  neededVersions {
  "659ef412370fa3b41cd7bf6e94587c1dfb7f67e7": {
    "engines": [
      "libqueryEngine"
    ],
    "binaryTargets": []
  }
} +0ms
  prisma:getGenerators  {
  generatorBinaryPaths: {
    libqueryEngine: {
      'darwin-arm64': './node_modules/.pnpm/[email protected]/node_modules/prisma/libquery_engine-darwin-arm64.dylib.node'
    }
  }
} +25ms
  prisma:GeneratorProcess  2023-04-06T15:40:51.229Z prisma:loadEnv  project root found at ./package.json +58ms
  prisma:GeneratorProcess  Error: unable to write files for Prisma Docs Generator +83ms
Error: Error: 
✔ Generated Prisma Client (4.12.0 | library) to ./node_modules/.pnpm/@[email protected][email protected]/node_modules/@prisma/client in 83ms

Cannot read properties of undefined (reading 'join')
    at _Generate.parse (./node_modules/.pnpm/[email protected]/node_modules/prisma/build/index.js:101892:15)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async main (./node_modules/.pnpm/[email protected]/node_modules/prisma/build/index.js:103530:18)

Environment:

OS: macOS 13.1 (22C65)
node.js: v19.3.0
Prisma: v4.12.0
primsa-docs-generator: v0.6.0

Separate out transforms and renderers from the generators

Likely after the mvp

Handle express server 404 with a proper page.

Right now it just shows this, we should add an instruction.

CLI is unable to resolve the prisma schema if it is in the docs folder

TypeError

Hi @pantharshit00 since upgrading to latest Prisma, I’m getting the following error:

TypeError: Cannot read property 'type' of undefinedat /__PATH__/node_modules/prisma-docs-generator/dist/generator/model.js:393:47
    at Array.map (<anonymous>)
    at /__PATH__/node_modules/prisma-docs-generator/dist/generator/model.js:391:90
    at Array.forEach (<anonymous>)
    at ModelGenerator.getModelOperations (/__PATH__/node_modules/prisma-docs-generator/dist/generator/model.js:267:18)
    at /__PATH__/node_modules/prisma-docs-generator/dist/generator/model.js:506:34
    at Array.map (<anonymous>)
    at ModelGenerator.getModels (/__PATH__/node_modules/prisma-docs-generator/dist/generator/model.js:500:38)
    at ModelGenerator.getData (/__PATH__/node_modules/prisma-docs-generator/dist/generator/model.js:512:26)
    at new ModelGenerator (/__PATH__/node_modules/prisma-docs-generator/dist/generator/model.js:35:26)

Removing prisma-docs-generator fixed the error, obviously, but it also means I can’t use it. Really hope your Prisma Docs Generator makes it into production at Prisma!

Can you add an option about that?