Adding more error codes to the OpenAPI generator?

[John4266]

Hello.
I am using express-zod-api in a project and I would like to know if it's possible to add more error codes for each endpoint in the OpenAPI generation.

For example, right now the OpenAPI spec generation only provides me with 200 code and 400 code for each endpoint.
But lets say my endpoints might respond with other error codes such as 500 with different type of response, or they might even respond with some code from a range of codes like 500 - 503 for different types of inputs, how would I add such responses to the getSpecAs(Yaml/JSON)?

I thought if I use, for example, throw createHttpError(409, "Email is already in use!"); in a signup endpoint, it would detect it and add it to the OpenAPI, but I guess it isn't a thing (yet).

I would also like to thank the creator for making such a great library with many great features.

[RobinTail]

Hello @John4266 ,

Thank you for your feedback and ideas.
Unfortunately, OpenAPI generator can not figure out anything from the code of the implementation.
Instead it works in the explicit way based on the static declaration of the Endpoint's and ResultHandler's schemas.

About the errors and their codes.
Regardless the particular HTTP error code you throw inside the Endpoint's handler, the case will be handled over to the ResultHandler, the entity responsible for the consistency of responses.
In the ResultHandler you can define two schemas: for a positive response and for a negative one (in case of an error).
That means that in case of any error the actual response must comply the predefined schema, no matter what HTTP Error code is implied.

The defaultResultHandler has the following schema of the negative response:

z.object({
  status: z.literal("error"),
  error: z.object({
    message: z.string(),
  }),
});

The HTTP Error code meanwhile goes to the status code of the response.
However, if you find this not enough for your case, you can copy and improve the defaultResultHandler according to your needs.

If you want your negative response to have particular fields only in case of specific errors, you can define the schema with optional fields. Like this:

z.object({
  status: z.literal("error"),
  error: z.object({
    code: z.number().optional(),
    message: z.string(),
    tracing: z.array(z.string()).optional(),
    file: z.string().optional(),
    line: z.number().optional(),
  }),
  additionalInformation: z.record(z.string()).optional()
});

Then you can fulfill these optional fields in the implementation of your ResultHandler for those specific cases.

So, no matter is it 400, 409 or 500, the API informs the consumer on the error happened. All negative (error) responses have to be similar (comply the schema), but you can make some fields optional for specific needs. Then the consumer (Frontend) should decide what to do in accordance of the HTTP status code and the payload with all that information.

P.S. For the OpenAPI you can also supply those optional fields with descriptions, that would clarify in which cases they are present.

z.object({
  // ...
  additionalInformation: z.record(z.string()).optional().description("in case of 503")
});

I hope this would be helpful. Let me know.

[elmeister]

@RobinTail by the way, could you please share why do we have "400" status in every generated OpenAPI endpoint (see here), even when request is an empty object? I mean, there's nothing client can "request badly" in GET /v1/user/retrieve, why to specify "400" for it please?

[RobinTail]

The generator describes the schemas of the positive and the negative responses for each endpoint.
Any endpoint can fail. However, the OpenAPI specification requires schemas to be assigned to an HTTP code.
I've chosen 400 as the one to describe the negative response in case of an error. All negative responses have the same schema thanks to ResultHandler, so I've just chosen then one I like to describe the most likely case, since the I/O validation is the primary goal of the library, @elmeister