tedisagolli / nextjs-routes-docs-generator

NextJS Routes Docs

Automatically generate Swagger Docs for your NextJS project.

• NextJS Routes Docs
  • Execute
  • Options
  • Example output
  • Support

For information about terms used in this document see: terminology

Execute

npx nextjs-routes-docs [dir]

Options

npx nextjs-routes-docs --help

Usage: npx nextjs-routes-docs [dir]

Arguments:
  dir                   Nextjs project directory

Options:
  -V, --version         output the version number
  -t, --text            Produce text docs
  -s, --swagger         Produce swagger docs
  -p, --params          [BETA] Parse code to get params
  -o, --output <value>  Choose output folder
  -h, --help            display help for command

Example output

Swagger: routes.yml

swagger: '2.0'
info:
  title: Swagger API
  version: 1.0.0
paths:
  /api/room/join:
    post:
      parameters:
        - in: body
          name: roomId
        - in: body
          name: user
  /api/room/update:
    post:
      parameters:
        - in: body
          name: roomId
        - in: body
          name: roomName
        - in: body
          name: roomSize
  /api/room:
    post:
      parameters:
        - in: body
          name: roomId
        - in: body
          name: createdBy
    get:
      parameters:
        - in: query
          name: roomId
    delete:
      parameters:
        - in: query
          name: roomId
  /api/user:
    post:
      parameters:
        - in: body
          name: userId
        - in: body
          name: userName
    get:
      parameters:
        - in: query
          name: userId

Plain text: routes

C:\Users\Tedis\Desktop\src\nextjs-project\pages\api\room\join.js
POST 	 /api/room/join 	 {body: {roomId, user}}
---------------------------------
C:\Users\Tedis\Desktop\src\nextjs-project\pages\api\room\update.js
POST 	 /api/room/update 	 {body: {roomId, roomName, roomSize}}
---------------------------------
C:\Users\Tedis\Desktop\src\nextjs-project\pages\api\room.js
POST 	 /api/room 	 {body: {roomId, createdBy}}
GET 	 /api/room 	 ?roomId
DELETE 	 /api/room 	 ?roomId
---------------------------------
C:\Users\Tedis\Desktop\src\nextjs-project\pages\api\user.js
POST 	 /api/user 	 {body: {userId, userName}}
GET 	 /api/user 	 ?userId
---------------------------------

Support

1. Crete an an issue in the public Github
2. Email [email protected]

nextjs-routes-docs-generator's Issues

[ERROR] Cannot find module 'babylon'

Hi,

When i use pnpx nextjs-routes-docs ./,an error occurred.

pnpx nextjs-routes-docs ./
.../share/pnpm/store/v3/tmp/dlx-31229    |  +21 ++
Packages are hard linked from the content-addressable store to the virtual store.
  Content-addressable store is at: /home/tohsaka888/.local/share/pnpm/store/v3
  Virtual store is at:             ../../../../.local/share/pnpm/store/v3/tmp/dlx-31229/node_modules/.pnpm
.../share/pnpm/store/v3/tmp/dlx-31229    | Progress: resolved 21, reused 21, downloaded 0, added 21, done
[ERROR] Cannot find module 'babylon'
Require stack:
- /home/tohsaka888/.local/share/pnpm/store/v3/tmp/dlx-31229/node_modules/.pnpm/[email protected]/node_modules/recast/parsers/babel.js
- /home/tohsaka888/.local/share/pnpm/store/v3/tmp/dlx-31229/node_modules/.pnpm/[email protected]/node_modules/recast/parsers/typescript.js
- /home/tohsaka888/.local/share/pnpm/store/v3/tmp/dlx-31229/node_modules/.pnpm/[email protected]/node_modules/nextjs-routes-docs/index.js

It does not support pnpm?

Cannot read property 'split' of undefined.

Hi there, interesting idea, I tried to run it in my NextJS+TypeScript project but got this error.

Any idea on why it might be?
I though maybe because Im on unix/macOs filesystem, maybe?
ERROR] Cannot read property 'split' of undefined

Fails if default export is a function invocation

If a route file exports the result of a function invocation, the generator will fail to parse the code.

eg

// as recommended by https://next-auth.js.org/getting-started/example
export default NextAuth({ config… })

or, as I sometimes do to wrap API routes with helper functions:

export default someHelperFunction(function handler(req, res) { … }));

In the former case, there's probably not much that can be done, but in the latter case, it would be nice if the doc generator could look at the callback function.

This causes failure at

nextjs-routes-docs-generator/index.js

Line 93 in c47c13f

mainFunction.value.declaration.params[0].name;

because mainFunction.value.declaration.params is undefined.

Fails if code contains `instanceof`

The generator fails if the instanceof operator is used in your code.

eg

if (foo instanceof SomeClass) …

Will cause the generator to print

[ERROR] Cannot read properties of undefined (reading 'name')

Because on

nextjs-routes-docs-generator/index.js

Line 22 in c47c13f

variable.object.name === reqVariableName &&

variable.object will be undefined, causing the read of .name to throw.

Not working for app directory

next-js-app/pages/api -> next-js-app/app/api

Typescript support

Running this on a typescript project causes the following error: [ERROR] Unexpected token (26:12)

The full error being thrown is:
SyntaxError: Unexpected token (36:5) at Parser.pp$4.raise (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:3459:15) at Parser.pp$9.unexpected (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:760:10) at Parser.pp$9.expect (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:754:28) at Parser.pp$7.parseBindingList (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:2026:19) at Parser.pp$8.parseFunctionParams (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:1368:24) at Parser.pp$8.parseFunction (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:1357:10) at Parser.pp$8.parseExport (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:1669:33) at Parser.pp$8.parseStatement (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:936:76) at Parser.pp$8.parseTopLevel (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:817:23) at Parser.parse (/PATH-TO-PROJECT-DIR/node_modules/acorn/dist/acorn.js:589:17) { pos: 907, loc: Position { line: 36, column: 5 }, raisedAt: 908 }

Digging further, it appears that the acorn parser doesn't natively support typescript but there are some spin-off projects that do.

Is there any interest in updating this to support typescript or should I make my own fork of this project?

Node 14 file.replaceAll is not a function