Вас тоже мучают проекты без документации? У вас тоже болит голова из-за того, что проекту нужно писать документацию? Вы тоже попадаете в ловушку устаревшей документации? Молодой человек, съешьте мои волосы Amway! Развернув Swagger, вы избавитесь от этих проблем. Красивая, легко читаемая, тестируемая и срочная документация, разве вы не хотите попробовать?
Показать результаты
Без лишних слов, давайте посмотрим непосредственно на окончательный эффект, черный корм для собак!
шаг 1. Добавьте комментарий в интерфейс
шаг 2. Просмотрите структуру Json, автоматически сгенерированную в соответствии с аннотацией
шаг 3. Автоматически генерировать документы в соответствии со структурой Json
шаг 4. Вы можете протестировать вызов интерфейса через документ
причина
Как разработчику писать документацию очень больно, основные болевые точки следующие (личное мнение):
- Отдельно от разработки, в процессе написания документации необходимо переключаться между документацией и кодом. неэффективный
- После логического обновления кода документацию нужно обновить в другом месте. беда
- Код был полностью прокомментирован и нуждается в повторном переводе в документацию. дублирование работы
На самом деле, если обобщить одним словом - ленивый.
Исходя из вышеперечисленных пунктов, арендодатель стал задумываться, а есть ли какой-нибудь инструмент, способный автоматически генерировать документы на основе аннотаций? Во всяком случае, время, затрачиваемое на разработку и производство документации, сокращается, предотвращается дублирование усилий, а доступность документации может быть гарантирована (предотвращается неисправность).
Введение в чванство
Первый взгляд на официальное определение
Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.
Проще говоря, Swagger на самом деле является спецификацией описания интерфейса. Пока интерфейс описывается в соответствии с этой спецификацией и добавляются комментарии, можно создавать структурированные данные, а затем инструменты, предоставляемые Swagger, можно использовать для создания красивых документов интерфейса. Итак, во введении упоминается«Развернуть чванство», если быть точным, должно быть«Развернуть спецификацию Swagger».
Идеи генерации документов
развертывать
-
Внедрить SDK в проект
composer require zircote/swagger-php -
Аннотировать интерфейс
После вступления вы можете напрямую добавлять комментарии к интерфейсу в соответствии со спецификациями SDK.
Swagger-php-example提供一个简单例子，以laravel/lumen框架为例 <?php namespace App\Http\Controllers; use Illuminate\Http\Request; class ExampleController extends Controller { /** * 这个一个需要实现的API * * 这部分是项目的基本描述，对于一个项目来说必须要有 * 由于是示例代码，所以把项目描述也放在了接口描述中，其实可以将这部分拆离到单独的文件中 * @SWG\Swagger( * schemes={"http"}, * host="somehost.webdev.com", * basePath="/api", * @SWG\Info( * title="这是一个测试项目", * version="1.0.0", * @SWG\Contact( * email="test@email.com" * ) * ) * ) * * 接下来是针对接口的描述 * @SWG\Get( * path="/v1/getsomething", * summary="这里是接口描述", * produces={"application/json"}, * 参数1 * @SWG\Parameter( * description="页码", * in="query", * name="pageNum", * type="number", * required=true * ), * 参数2 * @SWG\Parameter( * description="页面内容数", * in="query", * name="pageSize", * type="number" * ), * 响应体 * @SWG\Response( * response=200, * description="Success", * // 也可以添加返回数据的示例，这里不做赘述 * ) * 响应体 * @SWG\Response( * response=404, * description="Not Found", * ) * ) */ public function getSomeThing(Request $request) { // todo 待实现 } }Копируя пример выше, теперь у нас есть интерфейс со стандартными структурными аннотациями.
-
Интерфейс вызова строительства
После того, как аннотация построена, следующим шагом является вывод данных стандарта Swagger, Здесь мы выбираем Json в качестве выходной структуры.
Для удобства мы инкапсулируем логику получения данных Json в виде интерфейса, чтобы мы могли получить этот стандартный Swagger Json в любое время и в любом месте, Взяв за пример фреймворк Laravel/Lumen, простой пример выглядит следующим образом:
<?php namespace App\Http\Controllers; class SwaggerController extends Controller { public function getSwaggerJson() { // 该函数会扫描配置的目录地址下的文件，并将其中标准化的注释渲染为json数据 $swagger = \Swagger\scan(['需要扫描的目录1', '需要扫描的目录2', ...]); return response()->json($swagger, 200); } }Предоставьте другие официальные данные Json для справки:официальная ссылка
На данный момент через этот интерфейс можно получить стандартный Swagger Json, а следующим шагом будет отображение данных.
-
Отображение документа интерфейса
Показать методы сначала подумали, что Swagger-ui будет строить в одном из официальных услуг, и предоставить единый вход, затем думал, что этот подход слишком ограничен, не может никуда идти, в любое время, чтобы просмотреть документ, но и для записи сервисного адреса. Отказ
Позже выяснилось, можно ли для этого использовать плагин Chrome? После некоторых исследований выясняется, что некоторые предшественники пошли по этому пути, и уже есть готовые плагины, которые можно использовать.
После установки плагина, как показано в начале статьи, на основе страницы интерфейса нажмите, чтобы открыть плагин Swagger-ui, чтобы получить документацию, и вы можете выполнять такие операции, как тестирование интерфейса.
На данный момент настроена простая и эффективная среда Swagger, как ею пользоваться, зависит от ваших предпочтений.Hope you enjoy it!
Справочные документы
Swagger-uiНуждающиеся студенты могут создать свой собственный интерфейс Swagger