Swagger Specs Never Read for nesting pages etc into the 'src' directory

[jersmart]

Describe the bug

The api swagger docs are never read, so there is no api information generated. To recreate the repro:

1. npx create-next-app
2. pnpm i next-swagger-doc swagger-ui-react
3. follow the instructions here: https://www.npmjs.com/package/next-swagger-doc

I tried to identify the issue by piecemealing elements from the next 13/14 examples, but couldn't identify the root cause.

Reproduction

https://github.com/jersmart/next-swagger-doc-repro

System Info

System:
    OS: Linux 5.15 Ubuntu 22.04.2 LTS 22.04.2 LTS (Jammy Jellyfish)
    CPU: (16) x64 Intel(R) Core(TM) i9-9900K CPU @ 3.60GHz
    Memory: 5.68 GB / 15.59 GB
    Container: Yes
    Shell: 5.1.16 - /bin/bash
  Binaries:
    Node: 20.3.1 - ~/.nvm/versions/node/v20.3.1/bin/node
    npm: 9.6.7 - ~/.nvm/versions/node/v20.3.1/bin/npm
    pnpm: 8.6.3 - ~/.nvm/versions/node/v20.3.1/bin/pnpm

Used Package Manager

pnpm

Validations

• Follow our Code of Conduct
• Read the Contributing Guide.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A, please open a GitHub Discussion instead.
• The provided reproduction is a minimal reproducible of the bug.

[jellydn]

Hi @jersmart Did you try the example apps on this repo yet?

[jersmart]

Hi @jersmart Did you try the example apps on this repo yet?

The example apps worked for me. The biggest difference between the example apps and what's generated by create-next-app is nesting pages etc into the 'src' directory. However, when I try to change

apiFolder: 'pages/api' -> 'src/pages/api'

I get the following error:

- error Error: EISDIR: illegal operation on a directory, read at Object.readSync (node:fs:760:3) at tryReadSync (node:fs:440:20) at Object.readFileSync (node:fs:486:19) at extractAnnotations (/home/example/node_modules/.pnpm/swagger-jsdoc@6.2.8_openapi-types@12.1.3/node_modules/swagger-jsdoc/src/utils.js:54:26) at build (/home/example/node_modules/.pnpm/swagger-jsdoc@6.2.8_openapi-types@12.1.3/node_modules/swagger-jsdoc/src/specification.js:200:9) at Object.module.exports [as default] (/home/example/node_modules/.pnpm/swagger-jsdoc@6.2.8_openapi-types@12.1.3/node_modules/swagger-jsdoc/src/lib.js:32:10) at createSwaggerSpec (/home/example/node_modules/.pnpm/next-swagger-doc@0.4.0-1_next@13.4.12_openapi-types@12.1.3/node_modules/next-swagger-doc/dist/swagger-99304a1e.cjs:61:48) at getApiDocs (webpack-internal:///./src/swagger.ts:9:85) at getServerSideProps (webpack-internal:///./src/pages/api-doc/index.tsx:30:76) at fn (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/render.tsx:1028:11) at /home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/lib/trace/tracer.ts:261:28 at NoopContextManager.with (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:7057) at ContextAPI.with (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:516) at NoopTracer.startActiveSpan (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:18086) at ProxyTracer.startActiveSpan (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:18847) at /home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/lib/trace/tracer.ts:238:32 at NoopContextManager.with (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:7057) at ContextAPI.with (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:516) at NextTracerImpl.trace (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/lib/trace/tracer.ts:237:28) at renderToHTMLImpl (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/render.tsx:1019:32) at async doRender (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/base-server.ts:1802:18) at async cacheEntry.responseCache.get.incrementalCache.incrementalCache (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/base-server.ts:2031:24) at async /home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/response-cache/index.ts:126:28 { digest: undefined }

[jersmart]

Hi @jersmart Did you try the example apps on this repo yet?

The example apps worked for me. The biggest difference between the example apps and what's generated by create-next-app is nesting pages etc into the 'src' directory. However, when I try to change

apiFolder: 'pages/api' -> 'src/pages/api'

I get the following error:

- error Error: EISDIR: illegal operation on a directory, read at Object.readSync (node:fs:760:3) at tryReadSync (node:fs:440:20) at Object.readFileSync (node:fs:486:19) at extractAnnotations (/home/example/node_modules/.pnpm/swagger-jsdoc@6.2.8_openapi-types@12.1.3/node_modules/swagger-jsdoc/src/utils.js:54:26) at build (/home/example/node_modules/.pnpm/swagger-jsdoc@6.2.8_openapi-types@12.1.3/node_modules/swagger-jsdoc/src/specification.js:200:9) at Object.module.exports [as default] (/home/example/node_modules/.pnpm/swagger-jsdoc@6.2.8_openapi-types@12.1.3/node_modules/swagger-jsdoc/src/lib.js:32:10) at createSwaggerSpec (/home/example/node_modules/.pnpm/next-swagger-doc@0.4.0-1_next@13.4.12_openapi-types@12.1.3/node_modules/next-swagger-doc/dist/swagger-99304a1e.cjs:61:48) at getApiDocs (webpack-internal:///./src/swagger.ts:9:85) at getServerSideProps (webpack-internal:///./src/pages/api-doc/index.tsx:30:76) at fn (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/render.tsx:1028:11) at /home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/lib/trace/tracer.ts:261:28 at NoopContextManager.with (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:7057) at ContextAPI.with (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:516) at NoopTracer.startActiveSpan (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:18086) at ProxyTracer.startActiveSpan (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:18847) at /home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/lib/trace/tracer.ts:238:32 at NoopContextManager.with (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:7057) at ContextAPI.with (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/dist/compiled/@opentelemetry/api/index.js:1:516) at NextTracerImpl.trace (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/lib/trace/tracer.ts:237:28) at renderToHTMLImpl (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/render.tsx:1019:32) at async doRender (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/base-server.ts:1802:18) at async cacheEntry.responseCache.get.incrementalCache.incrementalCache (/home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/base-server.ts:2031:24) at async /home/example/node_modules/.pnpm/next@13.4.12_patch_hash=tpbd5rbdpqoageh5z5zdjldhkq_@babel+core@7.23.2_react-dom@18.2.0_react@18.2.0/node_modules/next/src/server/response-cache/index.ts:126:28 { digest: undefined }

I found the root cause of this issue. I have directories in the api folder that have a period in them that simulate retrieval of a file but actually build them dynamically (fwiw, not my design decision.) The error is accurate; it's trying to read a directory like its a file because it looks like one. This error is reproducible in the example:

1. move the 'hello.ts' api endpoint into a folder called 'test.json'

[jersmart]

This appears to be due to a bug in the swagger-jsdoc repo: Surnet/swagger-jsdoc#388

[jellydn]

I see. I just converted this to discussion. This is upstream issue which I can't fix with next-swagger-doc.

[jersmart]

I decided to fork the swagger-jsdoc repo so I could fix the bug myself, then use pnpm override so next-swagger-doc uses my fork: "next-swagger-doc>swagger-jsdoc": "npm:@jersmart/swagger-jsdoc@^6.1.1". There has been some work to enhance the build with better error handling here which covers more use cases than the one my fix covers. Not sure if/when this will get released.