Hono•2mo ago

products/{id} APIs conflicting with products/my-products in generated doc with OpenAPI

I did put the {id} one after the my-products one, but it doesn't seem to work?

46 Replies

ambergristle•2mo ago

hey! what package are you using for openapi? *specifically to generate the docs view

MarvinKROP•2mo ago

"@scalar/hono-api-reference": "^0.5.175", Appreciate your time responding to this!

ambergristle•2mo ago

Happy to help! I’m afk rn, but I’ll try to repro when i get back @MarvinKR i'm not able to repro can you share the describeRoute for that /products/{id} endpoint

MarvinKROP•2mo ago

.get(
    "/:id",
    clerkMiddleware(),
    describeRoute({
      tags: ["Products"],
      description: "Fetch a specific product by ID",
      parameters: [
        {
          name: "id",
          in: "path",
          required: true,
          schema: productIdSchema,
        },
      ],
      responses: {
        200: {
          description: "Successfully retrieved product",
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  data: resolver(selectProductSchema),
                },
              },
            },
          },
        },
        400: {
          description: "Product ID is required",
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  error: {
                    type: "string",
                    example: "Product ID is required",
                  },
                },
              },
            },
          },
        },
        401: {
          description: "Unauthorized access",
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  error: {
                    type: "string",
                    example: "Unauthorized access",
                  },
                },
              },
            },
          },
        },
        404: {
          description: "Product not found",
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  error: {
                    type: "string",
                    example: "Product not found",
                  },
                },
              },
            },
          },
        },
      },
    }),

.get(
    "/:id",
    clerkMiddleware(),
    describeRoute({
      tags: ["Products"],
      description: "Fetch a specific product by ID",
      parameters: [
        {
          name: "id",
          in: "path",
          required: true,
          schema: productIdSchema,
        },
      ],
      responses: {
        200: {
          description: "Successfully retrieved product",
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  data: resolver(selectProductSchema),
                },
              },
            },
          },
        },
        400: {
          description: "Product ID is required",
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  error: {
                    type: "string",
                    example: "Product ID is required",
                  },
                },
              },
            },
          },
        },
        401: {
          description: "Unauthorized access",
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  error: {
                    type: "string",
                    example: "Unauthorized access",
                  },
                },
              },
            },
          },
        },
        404: {
          description: "Product not found",
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  error: {
                    type: "string",
                    example: "Product not found",
                  },
                },
              },
            },
          },
        },
      },
    }),

ambergristle•2mo ago

thanks! can you add syntax highlighting? it makes snippets much easier to read also, what's the url in your browser when you select that route e.g., http://localhost:3000/docs#tag/default/GET/users/{id} lol. so i'm not able to repro your issue, but scalar also isn't displaying the response schemas @MarvinKR have you tried removing the clerk middleware (or moving it after the spec)?

MarvinKROP•2mo ago

how do you do that? Don't you need premium discord?

ambergristle•2mo ago

Nope. Discord uses markdown syntax, so just add the language after the opening backticks: ```typescript

MarvinKROP•2mo ago

http://localhost:3001/api/docs#tag/products/GET/api/products/%7Bid%7D yeah didn't work, also changing the url name didn't affect it. I feel like it's an issue with: name: "id", in: "path",

ambergristle•2mo ago

hmmmm. this is mine: http://localhost:3000/docs#tag/users/GET/users/{id}

MarvinKROP•2mo ago

Yeah I just use api in my basepath but it's pretty much the same This is what I have in /openapi

"/api/products/{id}": {
"get": {
"responses": {
"200": {},
"400": {},
"401": {},
"404": {}
},
"operationId": "getApiProductsById",
"tags": [],
"description": "Fetch a specific product by ID",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"_def": {
"checks": [],
"typeName": "ZodString",
"coerce": false,
"zodOpenApi": {
"openapi": {
"ref": "ProductId"
}
}
},
"~standard": {
"version": 1,
"vendor": "zod"
}
}
},
{
"in": "param",
"name": "id",
"schema": {
"type": "string"
},
"required": true
}
]
},
"delete": {}
},

"/api/products/{id}": {
"get": {
"responses": {
"200": {},
"400": {},
"401": {},
"404": {}
},
"operationId": "getApiProductsById",
"tags": [],
"description": "Fetch a specific product by ID",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"_def": {
"checks": [],
"typeName": "ZodString",
"coerce": false,
"zodOpenApi": {
"openapi": {
"ref": "ProductId"
}
}
},
"~standard": {
"version": 1,
"vendor": "zod"
}
}
},
{
"in": "param",
"name": "id",
"schema": {
"type": "string"
},
"required": true
}
]
},
"delete": {}
},

ambergristle•2mo ago

try removing the parameters option when i try to set that option and use zValidator, the UI breaks using only zValidator seems to work (import { validator as zValidator } from "hono-openapi/zod";)

ambergristle•2mo ago

/openapi when using both

ambergristle•2mo ago

when using only params

ambergristle•2mo ago

with only zValidator

ambergristle•2mo ago

@Aditya Mathur is it expected behavior that when using hono-openapi/zod, setting parameters in describeRoute and using zValidator will duplicate the parameter in the spec?

  .get(
    '/users/:id',
    describeRoute({
      // this
      parameters: [
        {
          name: "id",
          in: "path",
          required: true,
          schema: z.string(),
        },
      ],
    }),
    // and also here
    zValidator('param', z.object({ id: z.string() })),
    async (c) => {}
  )

  .get(
    '/users/:id',
    describeRoute({
      // this
      parameters: [
        {
          name: "id",
          in: "path",
          required: true,
          schema: z.string(),
        },
      ],
    }),
    // and also here
    zValidator('param', z.object({ id: z.string() })),
    async (c) => {}
  )

Aditya Mathur•2mo ago

This was resolved in v0.4.5 what version are you using of hono-openapi? @MarvinKR

ambergristle•2mo ago

i'm using v0.4.5

ambergristle•2mo ago

running the code shared above generates the preceding screenshots

Aditya Mathur•2mo ago

Interesting, can you share a reproduction of this? And create a issue over here - https://github.com/rhinobase/hono-openapi/issues

GitHub

Issues · rhinobase/hono-openapi

A plugin for Hono to generate OpenAPI Swagger documentation - Issues · rhinobase/hono-openapi

Aditya Mathur•2mo ago

I am working on another issue right now, which might help this one too. Not sure but I will give it a try.

Aditya Mathur•2mo ago

Here is the PR which was merged https://github.com/rhinobase/hono-openapi/pull/64

GitHub

fix(core): allow to use validator repeatedly - merge parameters by ...

Resolves #63

MarvinKROP•2mo ago

"hono-openapi": "^0.4.5",

Aditya Mathur•2mo ago

I need to write some tests 🙃

MarvinKROP•2mo ago

Haha I've never done tests either 💀 removing parameters fixed it! thx!!!!

ambergristle•2mo ago

happy to help!

Aditya Mathur•2mo ago

@MarvinKR can you check if v0.4.6 solves this issue for you?

MarvinKROP•2mo ago

hey @Aditya Mathur now I have this issues when writing:

       requestBody: {
        description: "Search query",
        required: true,
        content: {
          "application/json": {
            schema: resolver(z.object({ query: z.string() }).openapi({
              ref: "SearchRequest",
            })),
          },
        },
      },

       requestBody: {
        description: "Search query",
        required: true,
        content: {
          "application/json": {
            schema: resolver(z.object({ query: z.string() }).openapi({
              ref: "SearchRequest",
            })),
          },
        },
      },

I get this error: Type 'ResolverResult' is not assignable to type 'ReferenceObject | SchemaObject | undefined'.ts(2322) index.d.ts(329, 9): The expected type comes from property 'schema' which is declared here on type 'MediaTypeObject' so now I had to do this for request body:

        content: {
          "application/json": {
            schema: {
              type: "object",
              required: ["query"],
              properties: {
                query: { type: "string" },
              },
            },
          },
        },

        content: {
          "application/json": {
            schema: {
              type: "object",
              required: ["query"],
              properties: {
                query: { type: "string" },
              },
            },
          },
        },

But it does work in content responses:

        200: {
          description: "Successfully processed search",
          content: {
            "text/event-stream": {
              schema: resolver(
                z
                  .object({
                    companies: z.array(z.any()).optional(),
                    products: z.array(z.any()).optional(),
                    totalResults: z.number(),
                  })
                  .openapi({ ref: "SearchResponse" })
              ),
            },
          },
        },

        200: {
          description: "Successfully processed search",
          content: {
            "text/event-stream": {
              schema: resolver(
                z
                  .object({
                    companies: z.array(z.any()).optional(),
                    products: z.array(z.any()).optional(),
                    totalResults: z.number(),
                  })
                  .openapi({ ref: "SearchResponse" })
              ),
            },
          },
        },

ambergristle•2mo ago

Can you share the full route definition that’s breaking? (The full describeRoute)

Aditya Mathur•2mo ago

Hey @MarvinKR, this is my code -

import { serve } from "@hono/node-server";
import { Hono } from "hono";
import {
  describeRoute,
  openAPISpecs,
} from "hono-openapi";
import {
  resolver,
  validator,
} from "hono-openapi/zod";
import { apiReference } from "@scalar/hono-api-reference";
import z from "zod";
import "zod-openapi/extend";

const app = new Hono();

app.get(
  "/",
  describeRoute({
    responses: {
      200: {
        description: "Hello World",
        content: {
          "text/plain": {
            schema: resolver(z.string()),
          },
        },
      },
    },
  }),
  validator(
    "query",
    z.object({
      pathParam: z.string().openapi({
        default: "Hello",
        example: "world",
      }),
    }),
  ),
  (c) => {
    return c.text("Hello World");
  },
);

app.get("/openapi", openAPISpecs(app));

app.get(
  "/docs",
  apiReference({
    theme: "saturn",
    spec: {
      url: "/openapi",
    },
  }),
);

const port = 3000;
console.log(
  `Server is running on http://localhost:${port}`,
);

serve({
  fetch: app.fetch,
  port,
});

import { serve } from "@hono/node-server";
import { Hono } from "hono";
import {
  describeRoute,
  openAPISpecs,
} from "hono-openapi";
import {
  resolver,
  validator,
} from "hono-openapi/zod";
import { apiReference } from "@scalar/hono-api-reference";
import z from "zod";
import "zod-openapi/extend";

const app = new Hono();

app.get(
  "/",
  describeRoute({
    responses: {
      200: {
        description: "Hello World",
        content: {
          "text/plain": {
            schema: resolver(z.string()),
          },
        },
      },
    },
  }),
  validator(
    "query",
    z.object({
      pathParam: z.string().openapi({
        default: "Hello",
        example: "world",
      }),
    }),
  ),
  (c) => {
    return c.text("Hello World");
  },
);

app.get("/openapi", openAPISpecs(app));

app.get(
  "/docs",
  apiReference({
    theme: "saturn",
    spec: {
      url: "/openapi",
    },
  }),
);

const port = 3000;
console.log(
  `Server is running on http://localhost:${port}`,
);

serve({
  fetch: app.fetch,
  port,
});

I am not getting any type errors can you share a reproduction of this on Stackblitz? or CodeSandbox

MarvinKROP•2mo ago

can you do an example with a post endpoint using requestbody ?

MarvinKROP•2mo ago

https://gist.github.com/procureezy/1d5a91ad41f16dfb3f3e5281b7fb6aa1

Gist

post endpoint

post endpoint. GitHub Gist: instantly share code, notes, and snippets.

ambergristle•2mo ago

thanks! to clarify, is your issue a TS error or a runtime error? i'm not seeing any issues with the TS

ambergristle•2mo ago

MarvinKROP•2mo ago

type issue: Type 'ResolverResult' is not assignable to type 'ReferenceObject | SchemaObject | undefined'.ts(2322) index.d.ts(329, 9): The expected type comes from property 'schema' which is declared here on type 'MediaTypeObject'

ambergristle•2mo ago

interesting. can you share a screenshot of the code/error? i can't repro i shared my package.json to make sure we're on the same versions

MarvinKROP•2mo ago

yeah same here: "@hono/zod-openapi": "^0.19.2", "@hono/zod-validator": "^0.4.3", "hono": "^4.7.2", "hono-openapi": "^0.4.6", "zod": "^3.24.1", "zod-openapi": "^4.2.3"

Aditya Mathur•2mo ago

Just share a screenshot of the type errors you are getting, then I can take a look too

MarvinKROP•2mo ago

ambergristle•2mo ago

any shot this is a conflict between hono-openapi and @hono/zod-openapi? idk that you want to be running both in a project there are no TS issues on my end when i copy+paste your snippet

Aditya Mathur•2mo ago

Quick question why are you passing this in describeRoute?

app.get(
  "/",
  describeRoute({
    responses: {
      200: {
        description: "Hello World",
        content: {
          "text/plain": {
            schema: resolver(z.string()),
          },
        },
      },
    },
  }),
  validator(
    "json",
    z.object({ query: z.string() }).openapi({
      description: "Search query",
      ref: "SearchRequest",
    }),
  ),
  (c) => {
    return c.text("Hello World");
  },
);

app.get(
  "/",
  describeRoute({
    responses: {
      200: {
        description: "Hello World",
        content: {
          "text/plain": {
            schema: resolver(z.string()),
          },
        },
      },
    },
  }),
  validator(
    "json",
    z.object({ query: z.string() }).openapi({
      description: "Search query",
      ref: "SearchRequest",
    }),
  ),
  (c) => {
    return c.text("Hello World");
  },
);

This is how you should do it You don't have to pass required, as that we can get from the schema

Aditya Mathur•2mo ago

Seems to be working fine with scalar

ambergristle•2mo ago

what about queries, params, etc?

Aditya Mathur•2mo ago

Yeah for them too use the validator

MarvinKROP•2mo ago

Thanks for this fix! Appreciate your time & help!

Gaming

Programming

products/{id} APIs conflicting with products/my-products in generated doc with OpenAPI

Did you find this page helpful?