MODLD-602 & FOLIO-3678: Use GitHub Workflows api-lint and api-schema-…

…lint and api-doc (#52) * MODLD-602 & FOLIO-3678: Use GitHub Workflows api-lint and api-schema-lint and api-doc * MODLD-602: Update workflow/api-**.yml files based on https://github.com/folio-org/.github/tree/master/workflow-templates
folio-org · Nov 22, 2024 · 1eb09ea · 1eb09ea
1 parent a305f4d
commit 1eb09ea
Show file tree

Hide file tree

Showing 5 changed files with 205 additions and 5 deletions.
diff --git a/.github/workflows/api-doc.yml b/.github/workflows/api-doc.yml
@@ -0,0 +1,91 @@
+name: api-doc
+
+# https://dev.folio.org/guides/api-doc/
+
+# API_TYPES: string: The space-separated list of types to consider.
+# One or more of 'RAML OAS'.
+# e.g. 'OAS'
+#
+# API_DIRECTORIES: string: The space-separated list of directories to search
+# for API description files.
+# e.g. 'src/main/resources/openapi'
+# NOTE: -- Also add each separate path to each of the "on: paths:" sections.
+# e.g. 'src/main/resources/openapi/**'
+#
+# API_EXCLUDES: string: The space-separated list of directories and files
+# to exclude from traversal, in addition to the default exclusions.
+# e.g. ''
+
+env:
+  API_TYPES: 'OAS'
+  API_DIRECTORIES: 'src/main/resources/swagger.api'
+  API_EXCLUDES: 'folio-modules.yaml'
+  OUTPUT_DIR: 'folio-api-docs'
+  AWS_S3_BUCKET: 'foliodocs'
+  AWS_S3_FOLDER: 'api'
+  AWS_S3_REGION: 'us-east-1'
+  AWS_S3_ACCESS_KEY_ID: ${{ secrets.S3_ACCESS_KEY_ID }}
+  AWS_S3_ACCESS_KEY: ${{ secrets.S3_SECRET_ACCESS_KEY }}
+
+on:
+  push:
+    branches: [ main, master ]
+    paths:
+      - 'src/main/resources/swagger.api/**'
+    tags: '[vV][0-9]+.[0-9]+.[0-9]+*'
+  workflow_dispatch:
+
+jobs:
+  api-doc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.REF }}
+          submodules: recursive
+      - name: Prepare folio-tools
+        run: |
+          git clone https://github.com/folio-org/folio-tools
+          cd folio-tools/api-doc \
+            && yarn install \
+            && pip3 install -r requirements.txt
+      - name: Obtain version if release tag
+        if: ${{ startsWith(github.ref, 'refs/tags/v') }}
+        run: |
+          version=$(echo ${GITHUB_REF#refs/tags/[vV]} | awk -F'.' '{ printf("%d.%d", $1, $2) }')
+          echo "VERSION_MAJ_MIN=${version}" >> $GITHUB_ENV
+      - name: Set some vars
+        run: |
+          echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> $GITHUB_ENV
+      - name: Report some info
+        run: |
+          echo "REPO_NAME=${{ env.REPO_NAME }}"
+      - name: Do api-doc
+        run: |
+          if test -n "${{ env.VERSION_MAJ_MIN }}"; then
+            echo "Docs for release version ${{ env.VERSION_MAJ_MIN }}"
+            option_release=$(echo "--version ${{ env.VERSION_MAJ_MIN }}")
+          else
+            option_release=""
+          fi
+          python3 folio-tools/api-doc/api_doc.py \
+            --loglevel info \
+            --types ${{ env.API_TYPES }} \
+            --directories ${{ env.API_DIRECTORIES }} \
+            --excludes ${{ env.API_EXCLUDES }} \
+            --output ${{ env.OUTPUT_DIR }} $option_release
+      - name: Show generated files
+        working-directory: ${{ env.OUTPUT_DIR }}
+        run: ls -R
+      - name: Publish to AWS S3
+        uses: sai-sharan/[email protected]
+        with:
+          access_key: ${{ env.AWS_S3_ACCESS_KEY_ID }}
+          secret_access_key: ${{ env.AWS_S3_ACCESS_KEY }}
+          region: ${{ env.AWS_S3_REGION }}
+          source: ${{ env.OUTPUT_DIR }}
+          destination_bucket: ${{ env.AWS_S3_BUCKET }}
+          destination_prefix: ${{ env.AWS_S3_FOLDER }}
+          delete: false
+          quiet: false
diff --git a/.github/workflows/api-lint.yml b/.github/workflows/api-lint.yml
@@ -0,0 +1,66 @@
+name: api-lint
+
+# https://dev.folio.org/guides/api-lint/
+
+# API_TYPES: string: The space-separated list of types to consider.
+# One or more of 'RAML OAS'.
+# e.g. 'OAS'
+#
+# API_DIRECTORIES: string: The space-separated list of directories to search
+# for API description files.
+# e.g. 'src/main/resources/openapi'
+# NOTE: -- Also add each separate path to each of the "on: paths:" sections.
+# e.g. 'src/main/resources/openapi/**'
+#
+# API_EXCLUDES: string: The space-separated list of directories and files
+# to exclude from traversal, in addition to the default exclusions.
+# e.g. ''
+#
+# API_WARNINGS: boolean: Whether to cause Warnings to be displayed,
+# and to fail the workflow.
+# e.g. false
+
+env:
+  API_TYPES: 'OAS'
+  API_DIRECTORIES: 'src/main/resources/swagger.api'
+  API_EXCLUDES: 'folio-modules.yaml'
+  API_WARNINGS: false
+
+on:
+  push:
+    paths:
+      - 'src/main/resources/swagger.api/**'
+  pull_request:
+    paths:
+      - 'src/main/resources/swagger.api/**'
+  workflow_dispatch:
+
+jobs:
+  api-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Prepare folio-tools
+        run: |
+          git clone https://github.com/folio-org/folio-tools
+          cd folio-tools/api-lint \
+            && yarn install \
+            && pip3 install -r requirements.txt
+      - name: Configure default options
+        run: |
+          echo "OPTION_WARNINGS=''" >> $GITHUB_ENV
+      - name: Configure option warnings
+        if: ${{ env.API_WARNINGS == 'true' }}
+        run: |
+          echo "OPTION_WARNINGS=--warnings" >> $GITHUB_ENV
+      - name: Do api-lint
+        run: |
+          python3 folio-tools/api-lint/api_lint.py \
+            --loglevel info \
+            --types ${{ env.API_TYPES }} \
+            --directories ${{ env.API_DIRECTORIES }} \
+            --excludes ${{ env.API_EXCLUDES }} \
+            ${{ env.OPTION_WARNINGS }}
diff --git a/.github/workflows/api-schema-lint.yml b/.github/workflows/api-schema-lint.yml
@@ -0,0 +1,47 @@
+name: api-schema-lint
+
+# https://dev.folio.org/guides/describe-schema/
+
+# API_DIRECTORIES: string: The space-separated list of directories to search
+# for JSON Schema files.
+# e.g. 'src/main/resources/openapi'
+# NOTE: -- Also add each separate path to each of the "on: paths:" sections.
+# e.g. 'src/main/resources/openapi/**'
+#
+# API_EXCLUDES: string: The space-separated list of directories and files
+# to exclude from traversal, in addition to the default exclusions.
+# e.g. ''
+
+env:
+  API_DIRECTORIES: 'src/main/resources/swagger.api'
+  API_EXCLUDES: ''
+
+on:
+  push:
+    paths:
+      - 'src/main/resources/swagger.api/**'
+  pull_request:
+    paths:
+      - 'src/main/resources/swagger.api/**'
+  workflow_dispatch:
+
+jobs:
+  api-schema-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Prepare folio-tools
+        run: |
+          git clone https://github.com/folio-org/folio-tools
+          cd folio-tools/api-schema-lint \
+            && yarn install \
+            && pip3 install -r requirements.txt
+      - name: Do api-schema-lint
+        run: |
+          python3 folio-tools/api-schema-lint/api_schema_lint.py \
+            --loglevel info \
+            --directories ${{ env.API_DIRECTORIES }} \
+            --excludes ${{ env.API_EXCLUDES }}
diff --git a/Jenkinsfile b/Jenkinsfile
@@ -5,11 +5,6 @@ buildMvn {
   doUploadApidocs = true
   buildNode = 'jenkins-agent-java17'
 
-  doApiLint = true
-  doApiDoc = true
-  apiTypes = 'OAS'
-  apiDirectories = 'src/main/resources/swagger.api'
-
   doDocker = {
     buildDocker {
       publishMaster = true

diff --git a/src/main/resources/swagger.api/mod-linked-data.yaml b/src/main/resources/swagger.api/mod-linked-data.yaml
@@ -309,3 +309,4 @@ components:
           example: example/unknownError.sample
           schema:
             $ref: "#/components/schemas/errorResponse"
+
Original file line number	Diff line number	Diff line change
Expand Up		@@ -309,3 +309,4 @@ components:
		example: example/unknownError.sample
		schema:
		$ref: "#/components/schemas/errorResponse"