В своем первом рассказе из серии я объяснил, что трачу примерно день в неделю на решение интересующих меня проблем с крошечными программными приложениями. Я собирал набор инструментов для быстрого создания архитектурных шаблонов, которые, как я обнаружил, продолжают появляться в крошечных приложениях.
В более поздней истории я объяснил свой стек для создания крошечных API. Я использую Open API — открытый стандарт для определения контрактов API, который начал свою жизнь как Swagger. Swagger предоставляет красивый онлайн-редактор для работы со спецификациями в браузере. Я импортирую определение Open API для создания конфигурации AWS Gateway в конвейерах CI/CD и импортирую их в Postman для тестирования. Я использую Github Actions для выполнения тяжелой работы по созданию конфигураций шлюза API, а также по созданию и развертыванию кода Node.js в функциях GCP Firebase.
Улучшение опыта разработчиков
Спецификации Open API удобны, и здорово иметь возможность импортировать их в Postman, но мне очень нравится иметь старую добрую страницу документации API, которая объясняет назначение параметров и значение кодов состояния ошибки. Содержимое этой документации находится в моей спецификации Open API, но я хотел убедиться, что документы отображаются в размещенном статическом HTML и обновляются при каждом изменении API.
Swagger предоставляет инструмент под названием Swagger UI, который может генерировать HTML-сайт из спецификации, но для поддержки CI/CD я, как обычно, обратился к Github Actions. Сообщество меня еще не подвело, и на этот раз я нашел это действие, которому нужна только спецификация и имя для выходного каталога, и бум — генерация документов статического API. Объединив это с моими обычными действиями Github для развертывания S3 и аннулированием кеша Cloudfront, я через несколько минут получил автоматически обновляемый сайт документации по API:
jobs: deploy: name: Deploy runs-on: ubuntu-latest steps: - name: Checkout Repo uses: actions/checkout@master - name: Generate Swagger UI uses: Legion2/swagger-ui-action@v1 with: output: swagger-ui spec-file: nz-recycling-advanced-prod-oas30-apigateway.json - name: Deploy to S3 uses: jakejarvis/s3-sync-action@master with: args: --acl public-read --delete env: AWS_S3_BUCKET: www.cronin.nz DEST_DIR: apps/recycling-api-docs SOURCE_DIR: swagger-ui AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_REGION: us-west-2 - name: Invalidate Cloudfront cache uses: muratiger/invalidate-cloudfront-and-wait-for-completion-action@master env: DISTRIBUTION_ID: ${{ secrets.AWS_DISTRO }} PATHS: '/*' AWS_REGION: us-west-2 AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}