- PVSM.RU - https://www.pvsm.ru -
Продолжаем рассказывать [1] о применении на практике принципа работы с документацией как с кодом. В этот раз разберём получение спецификации Swagger напрямую из комментариев к коду API. В статье рассматривается роль технического писателя в процессе адаптации команды к использованию нового инструмента, а также приводятся конкретные инструкции по применению swagger-php в реальном проекте.
К 2021 году написано великое множество общедоступных библиотек на всех существующих языках программирования. У каждого разработчика есть уникальная возможность экономить своё время и решать сложные алгоритмические и вычислительные задачи, просто используя готовые решения, правильно встраивая их в свой код.
Наличие подробной и понятной документации изначально было необходимым условием успеха подобных библиотек, ведь они создавались для использования людьми, которые не имеют понятия о принципах их работы. Чтобы упростить получение такой документации, уже более 20-ти лет разрабатываются инструменты, которые позволяют собирать комментарии к коду, написанные по определённым правилам, и формировать из них HTML-страницы, PDF-документы или другие способы отображения структурированных данных. В этой статье речь пойдёт о примере практического применения одного из таких инструментов для документирования API, используемого командой Юлы.
В таблице приведены одни из самых популярных генераторов документации напрямую из кода, которые работают с интересующим нашу команду PHP:
Название | Первый релиз | Текущая версия | Языки, с которыми работает инструмент | Форматы вывода |
---|---|---|---|---|
Sphinx | 2008/03/21, v0.1.61611 [11] | 2020/12/24, v3.4.1 [12] | C, C++, PHP, Python, Ruby, JavaScript | HTML, CHM, LaTex, Man pages, ePub |
Doxygen | 1997/10/26 | 2020/12/27, Release_1_9_0 [13] | C/C++, Java, C#,, PHP, Python | HTML, CHM, RTF, LaTex, Man pages, Doc book, XML |
PhpDocumentor | 2011/02/01, v0.7.1 [14] | 2020/10/27, 3.0.0 [15] | PHP | HTML |
swagger-php | 2012/04/19, 0.1.0 [16] | 2020/12/02, 2.1.0 [17] | PHP | YAML, JSON |
На графике можно увидеть примерную оценку популярности инструментов, основанную на статистике GitHub: количество положительных отзывов — звёзд, а также количество копирований репозиториев:
Казалось бы, что может быть проще: разработчики сами оставляют комментарии к коду в нужном формате, а в процесс сборки проекта добавляется шаг, на котором запускается команда, которая разбирает комментарии и превращает их в HTML-страницы — и вуаля, документация готова. Но несмотря на видимую простоту процесса, в нём скрываются свои подводные камни.
Любой из вышеупомянутых инструментов требует определённой настройки, как минимум для кастомизации внешнего вида получаемых HTML-страниц. Установка и интеграция в процесс сборки тоже требуют отдельного внимания, хотя в большинстве случаев не представляют ничего сложного. Иногда проблемы с началом использования инструмента выходят за рамки технических сложностей и связаны с содержанием самих комментариев, особенно, если конечные потребители документации — внешние пользователи, а не только участники проекта. В этих случаях необходима экспертиза отдельного специалиста — технического писателя, основной задачей которого становится не столько написание самой документации, сколько правильная организация процессов вокруг её создания и изменение отношения к ней в целом. Важно перестроить
Swagger-php позволяет получать yaml-файл с документацией, составленной в соответствии со спецификацией OpenAPI [19], из аннотаций к коду, написанных по определённым правилам. На сайте разработчика [20] этого инструмента пользователю предлагается вариант установки с помощью Composer и несколько вариантов использования: вызывом процедуры непосредственно из PHP-кода, с помощью командной строки или запуском Docker-образа, загруженного из Docker Hub.
Принимая решение о ведении документации в комментариях к коду, мы руководствовались простой истиной — чем меньше лишних действий совершает и дополнительных инструментов использует разработчик, тем меньше времени он тратит на создание описаний и тем сложнее забыть или не успеть их добавить перед передачей работы на проверку коллегам.
Для нашей команды ключевой трудностью во внедрении swagger-php в процесс разработки стало отсутствие полноценного описания всех возможных аннотаций и атрибутов, которые могут быть в них указаны. Однако, в репозитории с проектом приведено несколько примеров [21] использования аннотаций, в том числе стандартный пример с описанием магазина домашних животных [22], указанный в качестве live-demo [23] интерфейса Swagger на официальном сайте.
Первым делом мы разобрали эти примеры и составили на их основе шаблоны аннотаций для PhpStorm, — live-templates [24], — которые значительно упростили написание комментариев и соблюдение единой структуры в проекте. Нам помогли сообщения об ошибках, которые генерирует swagger-php. В этих сообщениях выводится полный список атрибутов, которые могут быть заданы для используемой аннотации. На основании полученных таким образом списков мы и составили полные примеры для шаблонов.
Для тестирования работы инструмента, а также для прояснения вопроса о том, подойдёт ли он нашей команде и сможет ли вписаться в реалии процесса разработки, я переработал большой фрагмент старого незадокументированного кода, составил для него аннотации и получил первый конечный результат: yaml-файл с описанием части внутреннего API Юлы.
В ходе работы стало понятно, что некоторую информацию, имеющую отношение ко всему проекту, удобнее вынести в отдельные файлы и хранить в корне проекта в папке docs. В отдельный файл API_info.php мы вынесли аннотации, кратко характеризующие текущую версию документации:
Info
— заголовок спецификации, версия и краткое описание; Server
— краткое описание и URL серверов; SecurityScheme
— тип авторизации, используемый в методах API; ExternalDocumentation
— ссылка на страницу с внешней документацией, в нашем случае на базу знаний по всему проекту в Confluence.<?php
/**
* @OAInfo(
* title="Youla API", version="v1",
* description="Описание внутренних и внешних ручек API Юлы"
* )
* @OAServer(
* description="Youla API Stage",
* url=" . . . "
* )
* @OAServer(
* description="Youla API Local",
* url=" . . . "
* )
* @OASecurityScheme(
* type=". . . ",
* in=". . . ",
* securityScheme=". . . ",
* name=". . . "
* )
* @OAExternalDocumentation(
* description="Документация Backend",
* url="https://confluence.ru/. . . ",
* )
*/
use OpenApiAnnotations as OA;
Также мы создали отдельные файлы для описания групп тегов, выбранных в соответствии с внутренней логикой проекта. В этом разделе целесообразным было указать:
/**
* @OATag(
* name="b2b - products - vas",
* description="***Монетизация*** - Операции с VAS для b2b",
* @OAExternalDocumentation(
* description="VAS API",
* url="https://confluence.ru/. . . "
* )
* )
*/
Упомянутый выше документ — соглашение о наименовании сущностей Swagger — составили вместе с командой разработки. Он необходим для поддержания единого стиля описания в рамках проекта. В нем были приняты правила для сущностей Tag
, Schema
и Response
.
Следующим вопросом, который необходимо было решить, стал выбор способа отображения полученной спецификации.
Swagger предполагает несколько возможных вариантов предоставления доступа к документации конечным пользователям:
При выборе первого варианта вы получаете полный доступ ко всем компонентам интерфейса и можете изменять их в соответствии с требованиями вашего проекта. В нашем случае необходимо было:
Как это сделать:
git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui
npm run dev
Дождитесь, пока будут установлены необходимые зависимости и собрана текущая версия интерфейса, откройте http://localhost:3200/ [28] и убедитесь, что всё отображается корректно.
swagger-ui/src/plugins/topbar/
.topbar.jsx
в строке импорта замените название картинки на имя загруженного файла: import Logo from «./youla_logo_28.svg»
swagger-ui/src/style/
добавьте в файл _variables.scss
переменную $youla-bg-gradient
с указанием цвета, необходимого для вашего проекта: $youla-bg-gradient: linear-gradient(225deg, #F055FF 0%, #87A0FF 50%, #00FFFE 100%);
$topbar-background-gradient
: $topbar-background-gradient: $youla-bg-gradient !default;
background-color
на background
в файле _topbar.scss
: //background-color: $topbar-background-color;
background: $topbar-background-gradient;
download-url-input
и download-url-button
:
//control.push(<input className="download-url-input" type="text" onChange={ this.onUrlChange } value={this.state.url} disabled={isLoading} style={inputStyle} />)
)
//control.push(<Button className="download-url-button" onClick={ this.downloadUrl }>Explore
Пересоберите интерфейс с внесенными изменениями, выполнив команду npm run build
. После этого в папке dist/
будут обновлены все необходимые для загрузки на сервер файлы с интерфейсом.
В результате изменений верхняя панель будет выглядеть следующим образом:
Полный перечень скриптов, которые могут быть запущены в проекте swagger-ui, приведены в соответствующем файле репозитория [29].
Интерфейс Swagger позволяет выбирать файлы со спецификацией для отображения. Это оказалось удобно для некоторых проектов, в которых есть явное разделение конечных точек. Достаточно в папке dist/
в файле index.html
заменить переменную url
на массив urls
с именами и относительными адресами yaml файлов:
. . .
//url: "data/go-swagger.yaml",
urls: [
{
"url": "data/youla-ab-tests.yaml",
"name": "ab-tests"
},
{
"url": "data/youla-feed-pattern.yaml",
"name": "feed pattern"
},
{
"url": "data/go-swagger.yaml",
"name": "recommendation"
},
{
"url": "data/youla-stores.yaml",
"name": "stores"
},
],
. . .
В результате получим следующий вид верхней навигационной панели:
Процессы CI/CD в отношении документации были настроены коллегами из DevOps-подразделения команды, поэтому не буду останавливаться на этом подробно. В общих чертах сделали следующее:
master
автоматически синхронизируются с помощью rsync
с папками на сервере, отвечающем за rsync
полученный файл помещается в папку data/
для того интерфейса, к проекту которого относится спецификация.
Процесс добавления новой функциональности был расширен и стал включать в себя обязательное добавление аннотаций к коду всеми разработчиками:
Если же изначальным источником изменений является работа технического писателя, то процесс выглядит следующим образом:
После того, как добавление аннотаций к коду стало обязательным для всей новой функциональности, Swagger превратился в основной инструмент взаимодействия между командами разработки и тестирования. Процесс обновления и дополнения документации стал более регламентированным и прозрачным, что значительно упростило контроль актуальности и целостности итогового результата.
В 2021 году инструмент, подобный swagger-php, существует практически для любого языка программирования, что позволяет вести документацию в непосредственной близости от кода, а точнее, в самом коде. Таким образом, процессы хранения, проверки и обновления документации автоматически используют те же инструменты, которые применяются для работы с кодом, демонстрируя идеальный пример использования парадигмы Docs as code.
Автор: Алексей Солнцев
Источник [38]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/programmirovanie/361119
Ссылки в тексте:
[1] рассказывать: https://habr.com/ru/company/youla/blog/459640/
[2] Инструменты для генерирования документации из кода: #1
[3] Роль технического писателя при включении в процесс разработки нового инструмента: #2
[4] Пример использования swagger-php: #3
[5] Подготовка к работе: #4
[6] Swagger UI: #5
[7] Сборка проекта: #6
[8] Итоговый процесс: #7
[9] Заключение: #8
[10] Материалы для изучения: #9
[11] v0.1.61611: https://github.com/sphinx-doc/sphinx/releases/tag/v0.1.61611
[12] v3.4.1: https://github.com/sphinx-doc/sphinx/releases/tag/v3.4.1
[13] Release_1_9_0: https://github.com/doxygen/doxygen/releases/tag/Release_1_9_0
[14] v0.7.1: https://github.com/phpDocumentor/phpDocumentor/releases/tag/v0.7.1
[15] 3.0.0: https://github.com/phpDocumentor/phpDocumentor/releases/tag/v3.0.0
[16] 0.1.0: https://github.com/zircote/swagger-php/releases/tag/0.1.0
[17] 2.1.0: https://github.com/zircote/swagger-php/releases/tag/2.1.0
[18] мышление: http://www.braintools.ru
[19] спецификацией OpenAPI: http://spec.openapis.org/oas/v3.0.3
[20] сайте разработчика: https://zircote.github.io/swagger-php/Getting-started.html
[21] несколько примеров: https://github.com/zircote/swagger-php/tree/master/Examples
[22] магазина домашних животных: https://github.com/zircote/swagger-php/tree/master/Examples/petstore.swagger.io
[23] live-demo: https://petstore.swagger.io/?_ga=2.62124335.2091867336.1609937031-1144061170.1609937031
[24] live-templates: https://www.jetbrains.com/help/phpstorm/using-live-templates.html
[25] репозитория: https://github.com/swagger-api/swagger-ui
[26] инструкциям: https://github.com/swagger-api/swagger-ui/blob/ab7cefd5f1245a47f5ef2b9dad149d22e9d24656/docs/development/setting-up.md
[27] Node Package Manager: https://www.npmjs.com/get-npm
[28] http://localhost:3200/: http://localhost:3200/
[29] файле репозитория: https://github.com/swagger-api/swagger-ui/blob/ab7cefd5f1245a47f5ef2b9dad149d22e9d24656/docs/development/scripts.md
[30] хостинг: https://www.reg.ru/?rlink=reflink-717
[31] tico/swagger-php: https://hub.docker.com/r/tico/swagger-php
[32] Beth Aitman: https://bethaitman.com/
[33] Who write the docs?: https://www.writethedocs.org/videos/portland/2018/who-writes-the-docs-beth-aitman/
[34] Практический пример: https://dev.to/cjbrooks12/how-to-document-a-kotlin-project-edc
[35] Orchid: https://github.com/orchidhq/orchid
[36] Практический пример: https://pspdfkit.com/blog/2019/writing-and-maintaining-good-code-documentation/
[37] Jazzy: https://github.com/realm/jazzy
[38] Источник: https://habr.com/ru/post/537876/?utm_source=habrahabr&utm_medium=rss&utm_campaign=537876
Нажмите здесь для печати.