Swagger PHP упаковщик ответов - PullRequest
Новая
       24

Swagger PHP упаковщик ответов

0 голосов
/ 28 марта 2019

У меня есть приложение, написанное на Symfony 3.4, которое использует FOSRestBundle для предоставления контроллеров JSON, и я пытаюсь документировать свои API, используя NelmioApiDocBundle.

Я впервые использую NelmioApiDocBundle, а его документация разбросана по многим другим проектам.

Каждый контроллер возвращает один и тот же ответ. Это пример ответа success : 

{
    "status": "success",
    "data": {},
    "code": null,
    "message": null
}

Это пример ответа error : 

{
    "status": "error",
    "data": null,
    "code": 201,
    "message": "User not found."
}

А вот еще один: 

{
    "status": "error",
    "data": null,
    "code": 202,
    "message": "Invalid password."
}

Как видите, я просто изменяю статус с ошибкой / успехом и предоставляю числовой код для определения ошибки.

Как я могу описать это, используя аннотации Swagger, перерабатывая столько кода, сколько я могу? 

/**
 * @Route("/api/users")
 */
class UserController extends AbstractFOSRestController
{
    /**
     * User login.
     *
     * @Rest\Post("/login")
     * @SWG\Response(
     *     response=400,
     *     description="Username or password fields not found",
     *     @SWG\Schema(type="object",
     *         @SWG\Property(property="status", type="string"), <=== how can I say that it's error?
     *         @SWG\Property(property="data", type="object"),
     *         @SWG\Property(property="code", type="null"),     <=== how can I say that it's 201?
     *         @SWG\Property(property="message", type="string"),
     *     )
     *
     * )
     * @SWG\Response(
     *     response=200,
     *     description="Returns the user and the authentication token",
     *     @SWG\Schema(type="object",
     *         @SWG\Property(property="status", type="string"), <=== how can I say that it's success?
     *         @SWG\Property(property="data", type="object"),
     *         @SWG\Property(property="code", type="null"),
     *         @SWG\Property(property="message", type="string"),
     *     )
     * )
     * @SWG\Parameter(
     *     name="body",
     *     in="body",
     *     @SWG\Schema(type="object", required={"username"},
     *         @SWG\Property(property="username", type="string", example="admin"),
     *         @SWG\Property(property="password", type="string", example="admin")
     *     )
     * )
     * @SWG\Tag(name="users")
     * @Security(name="api_key")
     */
    public function loginAction(Request $request, UserPasswordEncoderInterface $encoder)
    {
    }
}
...