Как разработчик php, при использовании платформы Lumen для разработки микроуслуг всегда необходимо писать документы API. Популярный способ – использовать swagger для написания документов API. Но в отличие от родной поддержки языка Java для аннотаций, PHP может поддерживать только один документ swagger или добавлять аннотации к аннотациям для достижения аналогичных функций, но заметки Swagger написаны в аннотациях. Понимание болезненно, без подсказок кода, без форматирования.
Эта статья покажет вам, как использовать плагины аннотаций в phpstorm для быстрого создания документов swagger в коде при разработке проектов микросервисов Lumen (проекты Laravel похожи на другие проекты PHP).
Эта статья будет продолжать пересматриваться и обновляться. Для получения последней информации, пожалуйста, обратитесь к проекту Программы запрограммированного роста обезьян на моем GITHUB. Добро пожаловать в Star, пожалуйста, следуйте за мной для получения более захватывающего контента.
Конфигурация рамки
Мы используем последнюю версию Lumen 5.7 для демонстрации. Демонстрационный код был помещен в github. Вы можете обратиться к нему для вашего интереса.
https://github.com/mylxsw/lumen-swagger-demo
Зависимость от установки
В проекте Lumen сначала необходимо установить зависимости проекта SwaggerLume с помощью composer
composer require darkaonline/swagger-lume
Конфигурация проекта
останься bootstrap/app.php В файле удалите комментарии для следующей конфигурации (около 26 строк) и включите поддержку фасадов.
$app->withFacades();
Включить SwaggerLume Файл конфигурации проекта, в Зарегистрируйте привязки контейнеров Перед разделом добавьте
$app->configure('swagger-lume');
Затем в Регистрация Поставщиков услуг Часть, Регистрация SwaggerLume Поставщик услуг
$app->register(\SwaggerLume\ServiceProvider::class);
Выполните команды в корневом каталоге проекта php artisan swagger-lume:опубликовать Опубликовать конфигурации, связанные с swagger
После выполнения заказа в основном отражаются следующие изменения
- оставайтесь
config/В каталоге был добавлен файл конфигурации проектаswagger-lume.php - оставайтесь
ресурсы/просмотры/поставщикВ каталоге, сгенерированномswagger-lume/index.blade.phpПросмотр файла для предварительного просмотра сгенерированных документов API
Из файла конфигурации мы можем получить следующую ключевую информацию
- api.title В сгенерированном документе API отображается заголовок
- routes.api Адрес маршрутизации, используемый для доступа к сгенерированному интерфейсу документа API, по умолчанию равен
/api/документация - маршруты.документы Используется для доступа к исходному сгенерированному документу API, формат JSON, адрес маршрутизации по умолчанию
/docs - пути.документы и пути.docs_json По умолчанию объединяют адрес сгенерированного файла api-docs.json
хранилище/api-документы/api-документы.jsonВыполнитьphp-ремесленник чванство:создатьЭтот файл будет сгенерирован при выполнении команды
Автопрограмма грамматики
Чисто написанные от руки хвастливые аннотации определенно неизбежны. Они слишком подвержены ошибкам и требуют постоянного пересмотра грамматики ссылок на документы. Поэтому необходимо установить плагин, который может автоматически запрашивать грамматику аннотаций в аннотациях. Наша обычно используемая IDE-это phpstorm В phpstorm вам необходимо установить PHP-аннотацию Подключаемый модуль
После установки плагина, когда мы пишем документ Swagger, у нас есть функция автоматического запроса кода.
Написание документа
Документ Swagger содержит много информации, не связанной с конкретным API, и у нас есть приложение/Http/Контроллеры Создайте SwaggerController В этом контроллере мы не реализуем бизнес-логику, а используем ее только для размещения общей информации о документе.
[email protected]",
* name="mylxsw"
* )
* )
*
* @Server(
* url="http://localhost",
* description= "development environment"
* )
*
* @Schema(
* schema="ApiResponse",
* type="object",
* Description= "Response entity, response result uses this structure uniformly".
* ,
* @Property(
* property="code",
* type="string",
* description= "response code"
* ),
*@ Property (property = "message", type = "string", description = "response result prompt")
* )
*
*
* @package App\Http\Controllers
*/
class SwaggerController
{}Далее, в контроллере бизнес-логики мы можем написать API.
name = $request->input('name');
$resp->id = 123;
$resp->age = $request->input('age');
$resp->gender = $request->input('gender');
$prop1 = new DemoAdditionalProperty();
$prop1->key = "foo";
$prop1->value = "bar";
$prop2 = new DemoAdditionalProperty();
$prop2->key = "foo2";
$prop2->value = "bar2";
$resp->properties = [$prop1, $prop2];
return $resp;
}
}Здесь мы ссылаемся на тот, который определен в контроллере Swagger в результатах нашего ответа ApiResponse Это также относится к неопределенному объекту ExampleResp , мы можем app\Http\Responses Реализовать объект ExampleResp в каталоге (создайте каталог самостоятельно), где мы разместим все объекты ответа
Возвращаемый объект относится к другим объектам
Создание документов
Выполните следующую команду для создания документа, который находится в хранилище/api-docs/api-docs.json 。
php artisan swagger-lume:generate
предварительный просмотр файлов
Откройте браузер для доступа http://access адрес/документы, и вы можете увидеть следующее
Посещение http://access адрес/api/документация, и мы видим
Расширение Деталей Интерфейса
Больше
В этой статье кратко описывается, как использовать аннотации кода для автоматического создания документов Swagger в проекте Lumen и для взаимодействия с функцией запроса кода phpstorm. Однако одного их изучения недостаточно. Вам также необходимо понять грамматическую структуру документов Swagger в проекте swagger-php. Примеры В каталоге много примеров, вы можете обратиться к ним.
Документ swagger используется в командном проекте, но должно быть место для управления документом. Здесь мы рекомендуем проект Мастера. Этот проект представляет собой инструмент управления документами для совместной работы в команде. Он поддерживает документ Markdown и документ Swagger. Если вам интересно, вы можете попробовать.