Документирование ваших бессерверных решений 🚀
Пример создания и размещения вашей бессерверной документации, такой как OpenAPI / Swagger, ADR и документации по коду с TypeDoc.
Вступление
Довольно часто мы создаем фантастические бессерверные решения, но не уделяем должного внимания документации. Это может быть документ OpenAPI (Swagger) с описанием ваших API, документация по коду (с указанием ваших обработчиков лямбда-выражений, пакетов и т. Д. ), а также Записи решений по архитектуре (ADR).
В этой статье показано, как вы можете автоматически создать всю эту документацию для своих бессерверных решений, а также показать, как вы можете разместить ее для заинтересованных сторон (групп разработчиков, внешних компаний, независимых поставщиков программного обеспечения и т. Д.)
Вы можете получить доступ к репозиторию кода здесь, в котором для ясности есть подробные комментарии.
💡 Обратите внимание, что это минимальный код и архитектура для демонстрации использования создания различных частей документации, поэтому он не готов к производству и не соответствует передовым методам кодирования.
Что мы строим? 🏗️
На диаграмме ниже показана архитектура, которую мы строим в репо:
Архитектура основана на следующей статье с дополнительными шагами по созданию и размещению бессерверной документации 🔦
Этот пример архитектуры дает нам возможность работать, поэтому мы можем создать следующую документацию:
- Документ Swagger / OpenAPI для API.
- Документация по коду с использованием TypeDoc.
- Генерация ADR.
- Сгенерированная документация размещается на AWS S3 для просмотра.
Развертывание решения! 👨💻
🛑 Примечание. Выполнение следующих команд повлечет за собой расходы на вашу учетную запись AWS, поэтому измените конфигурацию соответствующим образом .
В корне папки запустите npm i, а затем npm run deploy:develop, который установит все зависимости и затем развернет на AWS.
Создание документации! 📝
Итак, мы развернули решение, теперь давайте посмотрим на результат!
OpenAPI / Swagger
Первая область документации, которую мы собираемся рассмотреть, - это документация OpenAPI / Swagger!
Мы используем плагин serverless-openapi-documentation-v2 с Serverless Framework для автоматического создания нашего документа OpenAPI / Swagger локально.
Это запускается в корне папки с помощью npm run openapi, а также является частью хука предварительной фиксации, который автоматически запускает его, когда вы фиксируете любые изменения в репозитории. Сгенерированный файл openapi.json показан ниже:
У нас есть отдельный файл для нашей документации по swagger под названием serverless.doc.yml, который затем связан в основном serverless.yml для каждой из конечных точек, как показано ниже:
Затем файл serverless.doc.yml содержит всю информацию OpenAPI, как и следовало ожидать, такую как модели, запросы / ответы, описания и т. Д. Базовый пример этого показан ниже:
Затем вы можете скопировать содержимое файла openapi.json, который был сгенерирован локально, и вставить его в swagger.io, чтобы просмотреть его, как показано ниже, чтобы убедиться, что он действителен:
В рамках бессерверного развертывания мы также автоматически размещаем это публично, используя бессерверный плагин s3, как показано ниже, который вы можете просмотреть, перейдя по URL-адресу соответствующей корзины S3 https://s3-openapi-develop.s3.eu-west-1.amazonaws.com/index.html#
Он автоматически передается в AWS S3 при бессерверном развертывании с использованием бессерверного подключаемого модуля s3 со следующей конфигурацией:
s3Sync:
- bucketName: ${self:custom.openapiBucket}
localDir: docs/openapi
acl: public-read
Как видно из нашей папки ./docs/openapi/static, мы используем папку dist из репозитория https://github.com/swagger-api/swagger-ui/tree/master/dist, чтобы мы могли разместить сгенерированный файл openapi.json. правильно на S3!
💡 Вы также можете сделать корзину S3 частной и разрешить доступ к ней только пользователям, которые, например, подключены к VPN, хотя в этой статье это не рассматривается.
Документация по коду
После развертывания бессерверный плагин s3 примет сгенерированную документацию по коду TypeDoc и разместит ее для нас публично на S3! Следующая конфигурация позволила нам это сделать:
s3Sync:
- bucketName: ${self:custom.docsBucket}
localDir: docs/documentation
acl: public-read
💡 Вы также можете сделать корзину S3 частной и разрешить доступ к ней только пользователям, которые, например, подключены к VPN, хотя в этой статье это не рассматривается.
Если вы сейчас перейдете в корзину AWS S3 docs, вы сможете просмотреть созданную вами документацию по решению! Например: https://s3-documentation-develop.s3.eu-west-1.amazonaws.com/index.html:
Индексная страница
На снимке экрана ниже показана автоматически сгенерированная страница индекса для документации, в которой ваши лямбда-функции перечислены справа:
Индивидуальные лямбда-функции
На снимке экрана ниже показана автоматически созданная страница для одной из лямбда-функций при нажатии на ссылку справа от страницы индекса:
💡 Очевидно, что вы можете создать документацию для любого кода, а не только для обработчиков лямбда-выражений, как в этом очень простом примере.
Существует хриплый хук перед фиксацией, который запускается npm run docs в корневой папке, поэтому при фиксации ваша документация всегда автоматически обновляется на случай, если вы забудете!
ADR (Записи решений по архитектуре)
Далее идут отчеты о решениях по архитектуре! Чтобы добавить новый ADR, вы можете выполнить следующую команду:
npm run adr:new — “add typedoc”
Это создаст для вас новый ADR в папке \docs\adr, как показано ниже:
Вы можете видеть, что у вас будет пронумерованный ADR для каждого принятого вами архитектурного решения, а также индексная страница «Прочтите меня»: README.md
Впоследствии вы можете указать свои ADR, используя следующую команду npm run adr:list, которая покажет в вашем терминале следующее:
А чтобы обновить существующий ADR, вы можете запустить npm run adr:update — “add typedoc".i.e. по ключу
Если вы хотите создать HTML-версию своих ADR локально, вы увидите export.html файл в корневой папке после запуска npm run adr:export:
🛑 Обратите внимание, что я на самом деле не описал контекст, решение или последствия, а это просто пример того, как их генерировать.
💡 Вы также можете разместить свои сгенерированные ADR так же, как мы сделали выше для OpenAPI и документации по коду!
Тестируем API! 🎯
Вы можете протестировать действующий функциональный API, если хотите, выполнив шаги тестирования, описанные в исходной статье (однако эта статья была посвящена исключительно созданию и размещению бессерверной документации).
Подведение итогов
Надеюсь, вы нашли это полезным в качестве легкого примера документирования ваших собственных бессерверных решений!
Я хотел бы связаться с вами по любому из следующих вопросов:
Https://www.linkedin.com/in/lee-james-gilmore/
https://twitter.com/LeeJamesGilmore
Если вы нашли статьи вдохновляющими или полезными, не стесняйтесь поддержать меня виртуальным кофе https://www.buymeacoffee.com/leegilmore, и в любом случае давайте подключимся и пообщаемся! ☕️
Если вам понравились публикации, пожалуйста, подпишитесь на мой профиль Ли Джеймс Гилмор для дальнейших публикаций / серий, и не забудьте подключиться и поздороваться 👋
Также используйте функцию «хлопать в ладоши» внизу сообщения, если она вам понравилась! (Можно хлопать больше одного раза !!)
Если вам понравилась эта статья, вам также может понравиться следующее:
Обо мне
«Привет, я Ли, сертифицированный технический архитектор AWS и ведущий инженер-программист из Великобритании, в настоящее время работаю техническим облачным архитектором и главным бессерверным разработчиком, в прошлом работал в основном над полнофункциональным JavaScript на AWS. 5 лет.
Я считаю себя проповедником бессерверных технологий и люблю все, что связано с AWS, инновациями, архитектурой программного обеспечения и технологиями. »
** Предоставленная информация является моим личным мнением, и я не несу ответственности за ее использование. ***
