Hono•7d 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?

27 Replies

ambergristle•7d ago

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

MarvinKROP•7d ago

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

ambergristle•7d 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•7d 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•7d 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•7d ago

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

ambergristle•7d ago

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

MarvinKROP•7d 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•7d ago

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

MarvinKROP•7d 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•7d 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•7d ago

/openapi when using both

ambergristle•7d ago

when using only params

ambergristle•7d ago

with only zValidator

ambergristle•7d 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) => {}
  )