来自枚举的 Swagger 预定义的返回类型值

Question

我需要能够告诉 Swagger API 文档某个 API 将返回某个枚举的子集。

假设我有一个枚举 UserType { User_Not_Found, User_Blocked, User_Duplicated, User_Active ...等等}。

一个 api/users/search 可能会返回用户 FullName 以防它找到匹配项或“User_Not_Found”以防它没有找到。

return Request.CreateResponse(
       success ? HttpStatusCode.OK : HttpStatusCode.BadRequest, 
       success ? fullName : UserType.User_Not_Found.ToString());

问题：我如何告诉 swagger 在此特定 API 上，如果找到匹配项，则返回可能返回全名，如果未找到匹配项，则返回“User_Not_Found”？

Answer 1

您想要做的很像让常规方法根据其执行返回 2 种不同的类型。 这是不可能的。

如果找到用户，我认为您应该使用 HttpStatusCode.OK 返回用户，否则返回包含在响应中的自定义异常，并使用 HttpStatusCode 401、403 或 404（根据您的需要）。这是您可以记录异常并且可以反映在 Swagger UI 中的原因。但是，这 不 反映 swagger.json 中的枚举。

    try
    {
        if (isUserFound)
        {
            return Request.CreateResponse(HttpStatusCode.OK, user);
        }
        throw new UserNotFoundException("User was not found");
    }
    catch (UserNotFoundException ex)
    {
        return Request.CreateResponse(HttpStatusCode.NotFound, ex);
    }