.gitlab-ci-check-apidocs.yml

# .gitlab-ci-check-apidocs.yml
#
# This gitlab-ci template validates Swagger API specification and
# triggers Mender API site rebuilds.
#
# The Mender API site rebuild is triggered automatically on production
# branches when there are changes to docs/*. Additionally, it can be
# manually triggered setting REBUILD_MENDER_API_DOCS to "true" when
# starting a pipeline.
#
# It assumes the documentation is in a docs/ folder.
#
# Add it to the project in hand through Gitlab's include functionality
#
# include:
#   - project: 'Northern.tech/Mender/mendertesting'
#     file: '.gitlab-ci-check-apidocs.yml'
#

stages:
  - test

test:apidocs:verify-yaml:
  tags:
    - mender-qa-worker-generic-light
  stage: test
  needs: []
  except:
    - /^saas-[a-zA-Z0-9.]+$/
  image: python:3-alpine
  before_script:
    # https://github.com/python/cpython/issues/95299
    - pip3 install pyyaml setuptools
    # Get our own Swagger verifier
    - wget https://raw.githubusercontent.com/mendersoftware/autodocs/master/verify_docs.py
  script:
    # Verify that the Swagger docs follow the autodeployment requirements
    - python3 verify_docs.py `find docs -name "*.yml"`

test:apidocs:verify-swagger:
  tags:
    - mender-qa-worker-generic-light
  stage: test
  needs: []
  except:
    - /^saas-[a-zA-Z0-9.]+$/
  image: node:alpine
  script:
    # Verify that the Swagger docs are valid
    - npm i -g @apidevtools/swagger-cli
    - npx @apidevtools/swagger-cli validate docs/*.yml

test:validate-open-api:
  tags:
    - mender-qa-worker-generic-light
  stage: test
  needs: []
  image:
    name: alpine
  before_script:
    - apk --update add curl
    - curl -L https://raw.github.com/stoplightio/spectral/master/scripts/install.sh -o install.sh
    - sh install.sh
  script:
    - |
      cat > .spectral.yaml << EOF
      extends: [['spectral:oas', all]]
      parserOptions:
        incompatibleValues: 1
      EOF
    - spectral lint -v -D -f text docs/*.yml
    - spectral lint -v -D -f junit -o spectral-report.xml docs/*.yml
  allow_failure: true
  artifacts:
    when: always
    expire_in: 2 weeks
    reports:
      junit: $CI_PROJECT_DIR/spectral-report.xml

trigger:apidocs:rebuild-mender-api-docs:
  tags:
    - mender-qa-worker-generic-light
  stage: .post
  variables:
    REBUILD_MENDER_API_DOCS: "false"
  rules:
    - changes:
      - docs/*
      if: '$CI_COMMIT_BRANCH =~ /^(master|staging|[0-9]+\.[0-9]+\.x)$/'
    - if: '$REBUILD_MENDER_API_DOCS == "true"'
  image: alpine
  before_script:
    - apk add git python3 py3-pip
    - wget https://raw.githubusercontent.com/mendersoftware/integration/master/extra/requirements.txt
    - pip3 install -r requirements.txt --break-system-packages
    - git clone https://github.com/mendersoftware/integration.git mender-integration
    - alias release_tool=$(realpath mender-integration/extra/release_tool.py)
    - apk add --no-cache curl
  script:
    # Enable the build of the mender-api-docs site versions where this branch is in use
    - BUILD_MASTER="false"
    - BUILD_HOSTED="false"
    # BUILD_VARS will contain version-specific flags e.g. (-F BUILD_2_5=true)
    # translating upstream/2.5.x to BUILD_2_x=true
    - BUILD_VARS=""
    - for version in $(release_tool --integration-versions-including ${CI_PROJECT_NAME} --version ${CI_COMMIT_REF_NAME} | cut -d"/" -f2); do
    -   if [ "${version}" == "master" ]; then
    -     BUILD_MASTER="true"
    -   elif [ "${version}" == "staging" ]; then
    -     BUILD_HOSTED="true"
    -   elif echo $version | grep -E -q -e '^[0-9.x]+$'; then
    -     VERSION_VAR_NAME=BUILD_$(echo $version | tr '.' '_' | sed -e 's/_x$//')
    -     BUILD_VARS="${BUILD_VARS} -F variables[${VERSION_VAR_NAME}]=true"
    -   fi
    - done
    # Trigger the rebuilds (master + production) of mender-api-docs, if at least one of the build is enabled
    - if [ "${BUILD_MASTER}" != "false" ] || [ "${BUILD_HOSTED}" != "false" ] || [ "${BUILD_VARS}" != "" ]; then
    -   BUILD_VARS_DEBUG=$(echo $BUILD_VARS | sed -e 's/-F //g')
    -   echo "Triggering mender-api-docs rebuild BUILD_MASTER=${BUILD_MASTER} BUILD_HOSTED=${BUILD_HOSTED} ${BUILD_VARS_DEBUG}"
    -   for ref in master production; do
    -     curl -v -f -X POST
            -F token=${MENDER_API_DOCS_TRIGGER_TOKEN}
            -F ref=$ref
            -F variables[BUILD_MASTER]=${BUILD_MASTER}
            -F variables[BUILD_HOSTED]=${BUILD_HOSTED}
            ${BUILD_VARS}
            https://gitlab.com/api/v4/projects/20356182/trigger/pipeline
    -   done
    - fi