В соавторстве с Джотисвараном Гнанасекараном, Свати Аккишетти, Чаран Сай, Харшей Судхир и Региной Шарон Г.
Добро пожаловать в третью часть серии статей о создании, тестировании и документировании REST API в PHP+Laravel.
Если вы еще не прошли первые две части, настоятельно рекомендую это сделать.
В этом выпуске основное внимание будет уделено созданию документации для REST API, которые мы создали и протестировали в предыдущих двух статьях.
Документирование API — очень важная, но часто упускаемая из виду часть процесса разработки. Это становится еще более важным, когда разработанные API-интерфейсы будут использоваться другой командой для интеграции в то, что они создают, возможно, что является очень распространенным сценарием в среде микросервисов.
Давайте быстро углубимся и посмотрим, как этого можно добиться в нашем проекте PHP+Laravel с помощью Swagger.
Swagger — это золотой стандарт документирования RESTful API. Хотя Swagger — это гораздо больше, чем просто инструмент для документирования, в этой статье мы в первую очередь сосредоточимся на его функции создания документов. Подробнее о Swagger можно прочитать здесь — https://swagger.io/
Установка и настройка Swagger:
Пакет Laravel, который нам нужен для этого — ‘DarkaOnLine/L5-Swagger’
Давайте установим это в наш проект Laravel.
Если вы следили за Частью I и Частью II серии, у вас уже должна быть настройка проекта. Если нет, настоятельно рекомендую вам ознакомиться с этими статьями перед началом работы, поскольку API, которые мы создаем в этих статьях, — это те, которые мы будем документировать здесь.
Откройте терминал, перейдите в каталог проекта и выполните следующую команду:
composer require darkaonline/l5-swagger
Установив пакет, давайте опубликуем конфигурацию swagger. Можно сделать с помощью этой команды:
php artisan vendor:publish — provider “L5Swagger\L5SwaggerServiceProvider”
Это должно создать файл с именем ‘l5-swagger.php’ в каталоге ‘config’ вашего проекта.
Вот некоторые из полезных значений в этом файле, которые вы можете изменить:
'route' => [
/*
* Route for accessing api documentation interface
*/
'api' => 'api/documentation',
],
‘api’ — представляет URL-адрес, который вы будете использовать для доступа к документации. Давайте изменим это как ‘/api/docs’
'generate_always' => env('L5_SWAGGER_GENERATE_ALWAYS', false),
‘generate_always’ — если вы хотите, чтобы документы генерировались автоматически каждый раз, когда вы вносите изменения, вы можете изменить это значение на ‘true’. Это лучше в среде DEV, конечно, не на производстве.
Создайте документы :
Теперь давайте попробуем сгенерировать документы, выполнив эту команду:
php artisan l5-swagger:generate
Когда вы выполните это, вы должны увидеть такую ошибку:
Это ожидаемо, так как мы еще не добавили никаких аннотаций в наш код, чтобы Swagger мог их подобрать. Давайте начнем это делать.
Аннотации:
Откройте базовый контроллер — app/Http/Controllers/Controller.php и добавьте эти строки чуть выше начала определения класса.
/** * @OA\Info( * title="BookShop API", * version="1.0.0", * ) */
Некоторая базовая аннотация, чтобы информировать Swagger о том, что такое API. Теперь запустите команду generate-docs, как и раньше, чтобы убедиться, что все в порядке.
Аннотируйте конечные точки:
Затем давайте добавим аннотации к различным конечным точкам API, которые в нашем случае будут методами маршрута в соответствующем контроллере.
Начнем с API GET.
Добавьте эти строки над методом getBook в файле ‘app/Http/Controllers/BookController.php:
/**
* @OA\Get(
* path="/books/{bookId}",
* operationId="getBook",
* tags={"getBook"},
* summary="Get details of a Book",
* description="Returns details of a Book",
* @OA\Parameter(
* name="bookId",
* description="Book Id",
* required=true,
* in="path",
* @OA\Schema(
* type="number"
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* type="object",
* @OA\Property(
* property="title",
* type="string",
* example="Hakuna Matata"
* ),
* @OA\Property(
* property="price",
* type="number",
* format="integer",
* example=200
* ),
* @OA\Property(
* property="author",
* type="object",
* example={
* "first_name": "John",
* "last_name": "Brown",
* "email":"[email protected]"
* },
* @OA\Property(
* property="first_name",
* type="string",
* example="John"
* ),
* @OA\Property(
* property="last_name",
* type="string",
* example="Brown"
* ),
* @OA\Property(
* property="email",
* type="string",
* example="[email protected]"
* ),
* ),
* ),
* ),
* @OA\Response(response=400, description="Bad request"),
* )
*
* Returns all the details for a given Book id
*/
Эти аннотации определяют входные требования для GET API вместе со структурой JSON ответа.
Краткий обзор аннотаций:
@OA — представляет спецификацию Open API. Подробнее здесь
@OA\Get — указывает метод HTTP, т. е. в данном случае GET. С ним будет связано много атрибутов, например:
‘path’ — URL конечной точки
‘tags’ — полезно для группировки API по разделам.
‘description’ — некоторая краткая информация об API, о котором здесь идет речь
@OA\Parameter — для GET API в нашем случае нужно передать bookID. Эта аннотация определяет этот входной параметр, его «тип» и т. д.
Затем следует Ответ
@OA\Response — у вас может быть несколько ответов на API. Мы добавляем один здесь для успешного ответа.
@OA\JsonContent — определяет структуру JSON, возвращаемого GET API. Этот JSON имеет несколько значений свойств различных типов, как вы видите в приведенной выше аннотации.
Эти свойства аннотируются с помощью:
@OA\Property —Каждое свойство имеет «ключ», который представляет собой имя и «тип». Существуют значения различных типов, такие как строка, число, целое число, логическое значение, массив и объект.
Ответ GET API, содержимое JSON, которое отправляется обратно, имеет «объект», который имеет поля «название» и «цена», а также другой встроенный объект, «автор», который содержит сведения об авторе.
Создать документы еще раз:
После добавления аннотаций мы можем сгенерировать документацию, запустив:
php artisan l5-swagger:generate
Интерфейс Swagger:
Теперь перейдите по URL-адресу, который вы настроили в ‘config/l5-swagger.php’, в нашем случае это — http://127.0.0.1:8000/api/docs.
Вы должны увидеть что-то вроде этого:
Разверните раздел, и вы увидите все подробности о конечной точке BookShop GET API, например:
В пользовательском интерфейсе также есть средство для быстрого вызова и тестирования API.
Круто, документация для GET готова!
Следуя аналогичному процессу, вы можете добавить аннотации для описания других конечных точек API (POST, PUT и DELETE).
Добавьте эти строки над методом ‘addBook’ (POST API) в файле ‘app/Http/Controllers/BookController.php:
/**
* @OA\POST(
* path="/books",
* summary="Add a new Book",
* tags={"addBook"},
* @OA\RequestBody(
* required = true,
* description = "New Book Details",
* @OA\JsonContent(
* type="object",
* @OA\Property(
* property="title",
* type="string",
* example="Davinci Code"
* ),
* @OA\Property(
* property="price",
* type="number",
* format="integer",
* example=550
* ),
* @OA\Property(
* property="author",
* type="object",
* example={
* "first_name": "Dan",
* "last_name": "Brown",
* "email": "[email protected]"
* },
* @OA\Property(
* property="first_name",
* type="string",
* example="Dan"
* ),
* @OA\Property(
* property="last_name",
* type="string",
* example="Brown"
* ),
* @OA\Property(
* property="email",
* type="string",
* example="[email protected]"
* ),
* ),
* ),
* ),
*
* @OA\Response(
* response=201,
* description="successful operation",
* @OA\JsonContent(
* type="string",
* example="Book is successfully added"
* ),
* ),
*
* )
*/
Добавьте эти строки над методом ‘updateBook’ (PUT API) в файле ‘app/Http/Controllers/BookController.php:
/**
* @OA\PUT(
* path="/books/{bookId}",
* summary="Update a Book",
* tags={"updateBook"},
* @OA\Parameter(
* name="bookId",
* description="Book Id",
* required=true,
* in="path",
* @OA\Schema(
* type="number"
* )
* ),
* @OA\RequestBody(
* required = true,
* description = "Update Book Details",
* @OA\JsonContent(
* type="object",
* @OA\Property(
* property="title",
* type="string",
* example="The Elephant Whisperer"
* ),
* @OA\Property(
* property="price",
* type="number",
* format="integer",
* example=850
* ),
* ),
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* type="string",
* example="Book is successfully updated"
* ),
* ),
* )
*/
Добавьте эти строки над методом ‘deleteBook’ (DELETE API) в файле ‘app/Http/Controllers/BookController.php’:
/**
* @OA\Delete(
* path="/books/{bookId}",
* operationId="deleteBook",
* tags={"deleteBook"},
* summary="Delete a Book",
* description="Deletes a Book",
* @OA\Parameter(
* name="bookId",
* description="Book Id",
* required=true,
* in="path",
* @OA\Schema(
* type="number"
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* type="string",
* example="Book is successfully deleted"
* ),
* ),
* @OA\Response(response=404, description="Book not found"),
* )
*
* Returns all the details for a given Book id
*/
После этих изменений повторно создайте документы API, выполнив эту команду:
php artisan l5-swagger:generate
Снова откройте пользовательский интерфейс Swagger или обновите страницу, если вы уже на ней находитесь.
Вы должны увидеть что-то вроде этого:
Поздравляем! Таким образом, вы успешно задокументировали все свои REST API, что является важной частью процесса разработки.
Вы можете найти весь код, над которым вы работали, в этой серии из 3 частей на GitHub:
Примечание. Код здесь предназначен только для образовательных и обучающих целей и определенно не готов к работе.
