generateOpenApiSpec returns empty spec

[GorgeousPuree]

import { LicenceDTO, LicencePatchDTO, NewLicenseDTO } from "@/models/license";
import generateOpenApiSpec from "@omer-x/next-openapi-json-generator";

export async function GET() {
  console.log(LicenceDTO)

  const spec = await generateOpenApiSpec({
    LicenceDTO,
    NewLicenseDTO,
    LicencePatchDTO
  });

  return Response.json(spec);
}

import { createInsertSchema } from "drizzle-zod";
import { licenses } from "@/database/schema";

const baseSchema = createInsertSchema(licenses, {
  id: schema => schema.id.readonly().describe("Unique identifier of the license"),
  licenseNumber: schema => schema.licenseNumber.describe("Number of the license"),
  country: schema => schema.country.describe("Country where license was issued"),
});

export const LicenceDTO = baseSchema.required()
  .describe("Represents a license definition");

  console.log(LicenceDTO)

export const NewLicenseDTO = baseSchema.omit({
    id: true,
  }).describe("Data Transfer Object for creating a new license");
  
export const LicencePatchDTO = NewLicenseDTO.partial().omit({
}).describe("Data Transfer Object for updating an existing license");

Although my DTOs are not empty, when I go to localhost:3000/api/swagger I have
{"openapi":"3.1.0","info":{"title":"Aaa","version":"0.1.0"},"paths":{},"components":{"schemas":{}},"tags":[]} as a result.

My package.json seems to be fine:

{
  "name": "aaa",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "c": "^0.11.0",
    "@omer-x/next-openapi-json-generator": "^1.2.1",
    "@omer-x/next-openapi-route-handler": "^1.6.0",
    "dotenv": "^16.4.5",
    "drizzle-orm": "^0.36.1",
    "drizzle-zod": "^0.5.1",
    "next": "15.0.3",
    "pg": "^8.13.1",
    "react": "19.0.0-rc-66855b96-20241106",
    "react-dom": "19.0.0-rc-66855b96-20241106",
    "swagger-ui-react": "^5.18.2",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@omer-x/openapi-types": "^1.1.0",
    "@types/node": "^20",
    "@types/pg": "^8.11.10",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "@types/swagger-ui-react": "^4.18.3",
    "drizzle-kit": "^0.28.0",
    "eslint": "^8",
    "eslint-config-next": "15.0.3",
    "postcss": "^8",
    "tailwindcss": "^3.4.1",
    "tsx": "^4.19.2",
    "typescript": "^5"
  }
}

I expected that the resulting schemas in spec would not be empty. What could be the reason for that?

[omermecitoglu]

Do you have any route? Recently I added a feature to delete unused schema components. I think that's why you see an empty spec. I can add an option to disable that feature If you need to use it this way.

[GorgeousPuree]

Do you have any route? Recently I added a feature to delete unused schema components. I think that's why you see an empty spec. I can add an option to disable that feature If you need to use it this way.

Yes, I do have a route:

import getLicenses from "@/operations/getLicenses";
import { LicenceDTO } from "@/models/license";
import defineRoute from "@omer-x/next-openapi-route-handler";
import z from "zod";

export const { GET } = defineRoute({
    operationId: "getLicenses",
    method: "GET",
    summary: "Get all users",
    description: "Retrieve a list of licenses",
    tags: ["Licenses"],
    queryParams: z.object({
      select: LicenceDTO.keyof().array().default([])
        .describe("List of the column names"),
    }),
    action: async ({ queryParams }) => {
      return Response.json(await getLicenses());
    },
    responses: {
      200: { description: "Returns a list of licenses", content: LicenceDTO, isArray: true },
    },
  });

And when I call it, it returns me a response that's expected:
[{"id":1,"licenseNumber":"123123","country":"AU"}]

Still Swagger schema is empty. Not sure why.

[GorgeousPuree]

Can't tell if it's related to my issue, but I'm also getting this error, when I try to open Swagger page. I assume that should be because generateOpenApiSpec returns me an empty spec.

Swagger page:

import generateOpenApiSpec from "@omer-x/next-openapi-json-generator";
import ReactSwagger from "@/components/ReactSwagger";
import { LicenceDTO } from "@/models/license";

const Page = async () => {
  const spec = await generateOpenApiSpec({
    LicenceDTO,
  });
  return <ReactSwagger spec={spec} />;
};

export default Page;

ReactSwagger:

"use client";
import SwaggerUI from "swagger-ui-react";
import "swagger-ui-react/swagger-ui.css";
import type { OpenApiDocument } from "@omer-x/openapi-types";

type ReactSwaggerProps = {
  spec: OpenApiDocument,
};

const ReactSwagger = ({
  spec,
}: ReactSwaggerProps) => (
  <SwaggerUI
    spec={spec}
    url="/swagger"
  />
);

export default ReactSwagger;

[omermecitoglu]

Which version of next.js are you using btw?

[GorgeousPuree]

Which version of next.js are you using btw?

"next": "15.0.3"

[omermecitoglu]

I didn't have time to test it with next 15 yet. Because I couldn't upgrade any of my next.js projects to 15. I can suggest you to stick with v14 until react 19 becomes stable.

[GorgeousPuree]

I didn't have time to test it with next 15 yet. Because I couldn't upgrade any of my next.js projects to 15. I can suggest you to stick with v14 until react 19 becomes stable.

Just downgraded to "react": "18.3.1" and "next": "14.1.1" and still getting empty spec.
By the way, my issue with React Swagger, I mentioned earlier has nothing to do with the original issue. I passed wrong url in:

<SwaggerUI
    spec={spec}
    url="/swagger"
  />

It should've been:

<SwaggerUI
    spec={spec}
    url="/api/swagger"
  />

Still looking why generateOpenApiSpec returns empty spec.

[omermecitoglu]

I'll look into it tomorrow if the problem still persists in next 14

[omermecitoglu]

It's obvious why the schemas don't appear is because there is no api routes in your specs.

The library thinks you didn't use any of the schemas and deletes them.

I added an option to disable that feature in v1.3

you need to add

generateOpenApiSpec(models, {
  clearUnusedSchemas: false, // <-- this
})

So we can be sure about schemas

On the other hand, we need to figure out why is paths section is empty in your specs

{
  "openapi":"3.1.0",
  "info":{"title":"Aaa","version":"0.1.0"},
  "paths":{},
  "components":{"schemas":{}},
  "tags":[]
}

But I need more information about that. I'd appreciate if you can provide a minimal reproducible example.

[GorgeousPuree]

because there is no api routes in your specs

Isn't my getLicenses endpoint, I described above, an api route? I declared it using defineRoute. Am I missing something in defining api routes?
Now when I'm using clearUnusedSchemas, I can see my schemas, but paths are empty.

Here I've created a minimal reproducible example: https://github.com/GorgeousPuree/omer-swagger-generator-test

[omermecitoglu]

Oh it's because the file name is route.tsx should be route.ts

[GorgeousPuree]

Oh it's because the file name is route.tsx should be route.ts

OHH, right, stupid typo. It finally worked. But I think it's worth mentioning that if you run app in the dev mode and go to api/swagger right away, it will give 500 error with TypeError: Cannot read properties of undefined (reading 'length'). That's because there's no precompiled route in .next/server/app/api/[your api route name]/route.js. But once you open your api endpoint (api/license in my case) or build prod next app, api/swagger returns correct spec, since now there's a corresponding route.js in the .next folder.

[omermecitoglu]

It used to work in dev mode. But then later I don't know what is changed between next.js versions. It doesn't work anymore. I will dig into it later. Or if you have a solution, you are welcome to make a PR.

[omermecitoglu]

And I'm closing this one.