В своем первом рассказе из серии я объяснил, что трачу примерно день в неделю на решение интересующих меня проблем с крошечными программными приложениями. Я собирал набор инструментов для быстрого создания архитектурных шаблонов, которые, как я обнаружил, продолжают появляться в крошечных приложениях.

В более поздней истории я объяснил свой стек для создания крошечных 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 }}