feat: OpenAPI Specification (#36)

Refs: #35
SchweizerischeBundesbahnen · Sep 3, 2024 · 25625d6 · 25625d6
1 parent 56372c3
commit 25625d6
Show file tree

Hide file tree

Showing 5 changed files with 740 additions and 118 deletions.
diff --git a/.github/workflows/maven-build.yml b/.github/workflows/maven-build.yml
@@ -15,23 +15,42 @@ jobs:
       GITHUB_TOKEN: ${{ github.token }}
       MARKDOWN2HTML_MAVEN_PLUGIN_FAIL_ON_ERROR: true
     steps:
-      - name: Checkout
+      # Checkout the repository
+      - name: 📄 Checkout
         uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  # v4
-      - name: Set up JDK and Maven
+        with:
+          fetch-depth: 0
+
+      # Set up JDK and Maven
+      - name: 🧱 Set up JDK and Maven
         uses: actions/setup-java@6a0805fcefea3d4657a47ac4c165951e33482018  # v4
         with:
           distribution: adopt
           java-version: 17
           gpg-private-key: ${{ secrets.COM_SONATYPE_CENTRAL_POLARION_OPENSOURCE_GPG_PRIVATE_KEY }}
-      - name: Prepare Cache
+
+      # Get the project version
+      - name: 📝 Store project version
+        id: project_version
+        run: echo "project_version=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)" >> $GITHUB_OUTPUT
+
+      # Generate cache key
+      - name: 📝 Store cache key
+        id: cache_key
+        run: echo "cache_key=${{ runner.os }}-mvn-${{ hashFiles('**/pom.xml') }}-${{ github.sha }}" >> $GITHUB_OUTPUT
+
+      # Prepare cache using cache key
+      - name: 💾 Prepare Cache
         id: prepare-cache
         uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9  # v4
         with:
           path: |
             /home/runner/.m2
             /home/runner/work
-          key: ${{ runner.os }}-mvn-${{ hashFiles('**/pom.xml') }}
-      - name: Generate settings.xml
+          key: ${{ steps.cache_key.outputs.cache_key }}
+
+      # Generate settings.xml for Maven
+      - name: 🔘 Generate settings.xml
         uses: whelk-io/maven-settings-xml-action@9dc09b23833fa9aa7f27b63db287951856f3433d  # v22
         with:
           repositories: >
@@ -78,21 +97,19 @@ jobs:
                 }
               }
             ]
-      - name: Print settings.xml
+
+      # Print settings.xml
+      - name: 🔘 Print settings.xml
         run: cat /home/runner/.m2/settings.xml
-      - name: Build with Maven
+
+      # Build with Maven
+      - name: 📦 Build with Maven
         run: mvn --batch-mode clean package
-      - name: Store project version
-        id: project_version
-        run: echo "project_version=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)" >> $GITHUB_OUTPUT
-      - name: Store cache key
-        id: cache_key
-        run: echo "cache_key=${{ runner.os }}-mvn-${{ hashFiles('**/pom.xml') }}" >> $GITHUB_OUTPUT
     outputs:
       project_version: ${{ steps.project_version.outputs.project_version }}
       cache_key: ${{ steps.cache_key.outputs.cache_key }}
 
-  # deploy to Maven Central
+  # Deploy release to Maven Central
   deploy-maven-central:
     needs: build
     runs-on: ubuntu-latest
@@ -104,21 +121,26 @@ jobs:
       COM_SONATYPE_CENTRAL_POLARION_OPENSOURCE_TOKEN: ${{ secrets.COM_SONATYPE_CENTRAL_POLARION_OPENSOURCE_TOKEN }}
       COM_SONATYPE_CENTRAL_POLARION_OPENSOURCE_GPG_PASSPHRASE: ${{ secrets.COM_SONATYPE_CENTRAL_POLARION_OPENSOURCE_GPG_PASSPHRASE }}
     steps:
-      - name: Set up JDK and Maven
-        uses: actions/setup-java@6a0805fcefea3d4657a47ac4c165951e33482018 # v4
+      # Set up JDK and Maven
+      - name: 🧱 Set up JDK and Maven
+        uses: actions/setup-java@6a0805fcefea3d4657a47ac4c165951e33482018  # v4
         with:
           distribution: adopt
           java-version: 17
           gpg-private-key: ${{ secrets.COM_SONATYPE_CENTRAL_POLARION_OPENSOURCE_GPG_PRIVATE_KEY }}
-      - name: Restore Cache
+
+      # Restore cache using cache key
+      - name: 💾 Restore Cache
         id: restore-cache
         uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9  # v4
         with:
           path: |
             /home/runner/.m2
             /home/runner/work
           key: ${{ needs.build.outputs.cache_key }}
-      - name: Publish to Maven Central
+
+      # Deploy artifacts to Maven Central
+      - name: 📦 Publish to Maven Central
         run: mvn --batch-mode -Dmaven.test.skip=true deploy -P gpg-sign -P nexus-staging
 
   # deploy to GitHub Packages
@@ -134,21 +156,28 @@ jobs:
       S3_SBB_POLARION_MAVEN_REPO_RW_SECRET_ACCESS_KEY: ${{ secrets.S3_SBB_POLARION_MAVEN_REPO_RW_SECRET_ACCESS_KEY }}
       GITHUB_TOKEN: ${{ github.token }}
     steps:
-      - name: Set up JDK and Maven
-        uses: actions/setup-java@6a0805fcefea3d4657a47ac4c165951e33482018 # v4
+      # Set up JDK and Maven
+      - name: 🧱 Set up JDK and Maven
+        uses: actions/setup-java@6a0805fcefea3d4657a47ac4c165951e33482018  # v4
         with:
           distribution: adopt
           java-version: 17
-      - name: Cache
-        id: cache
+
+      # Restore cache using cache key
+      - name: 💾 Restore Cache
+        id: restore-cache
         uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9  # v4
         with:
           path: |
             /home/runner/.m2
             /home/runner/work
           key: ${{ needs.build.outputs.cache_key }}
-      - name: Publish to GitHub Packages
+
+      # Deploy artifacts to GitHub Packages
+      - name: 📦 Publish to GitHub Packages
         run: mvn --batch-mode -Dmaven.test.skip=true -Dmaven.javadoc.skip=true -Dmaven.source.skip=true deploy -P deploy-github-packages
-      - name: Upload assets
-        run: cd ${{github.workspace}} && gh release upload v${{ needs.build.outputs.project_version }} target/*-${{ needs.build.outputs.project_version }}.jar
-        shell: bash
+
+      # Upload assets to GitHub Release
+      - name: 📦 Upload assets
+        run: |-
+          gh release upload v${{ needs.build.outputs.project_version }} **/target/*-${{ needs.build.outputs.project_version }}.jar
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -16,6 +16,8 @@ repos:
       - id: check-yaml
       - id: no-commit-to-branch
       - id: mixed-line-ending
+      - id: pretty-format-json
+        args: [--autofix, --no-ensure-ascii, '--top-keys=openapi,info,servers,paths,components']
   - repo: https://github.com/zricethezav/gitleaks
     rev: v8.18.4
     hooks:

diff --git a/README.md b/README.md
@@ -6,6 +6,7 @@ Column-to-Field mapping is manageable using mapping settings.
 ## Build
 
 This extension can be produced using maven:
+
 ```bash
 mvn clean package
 ```
@@ -25,7 +26,8 @@ For automated installation with maven env variable `POLARION_HOME` should be def
 Changes only take effect after restart of Polarion.
 
 ## Apache POI Polarion Bundle
-Latest Polarion installations have relatively old version of Apache POI so it is recommended to use Apache POI Polarion Bundle (for more information please check [ch.sbb.polarion.thirdparty.bundles](https://github.com/SchweizerischeBundesbahnen/ch.sbb.polarion.thirdparty.bundles)):
+
+Latest Polarion installations have relatively old version of Apache POI, so it is recommended to use Apache POI Polarion Bundle (for more information please check [ch.sbb.polarion.thirdparty.bundles](https://github.com/SchweizerischeBundesbahnen/ch.sbb.polarion.thirdparty.bundles)):
 its artifact must be placed to `<polarion_home>/polarion/extensions/ch.sbb.polarion.thirdparty.bundles.org.apache.poi/eclipse/plugins/org.apache.poi-<version>.jar`
 
 ## Polarion configuration
@@ -43,97 +45,10 @@ its artifact must be placed to `<polarion_home>/polarion/extensions/ch.sbb.polar
    ```
 5. Save changes by clicking 💾 Save
 
-## Extension's REST API
-
-### Settings
-
-Settings may be changed using `/api/settings/mappings/names/{mappingName}` endpoint.
-Request body example:
-
-```json
-{
-  "sheetName": "Sheet 1",
-  "startFromRow": 1,
-  "columnsMapping": {
-    "A": "title",
-    "B": "docId",
-    "C": "docName"
-  },
-  "defaultWorkItemType": "requirement",
-  "linkColumn": "B"
-}
-```
+## REST API
 
-List of workItem types for project may be accessible using `/api/projects/{projectId}/workitem_types` endpoint.
-Request body example:
-
-```json
-[
-  {
-    "sequenceNumber": 1,
-    "name": "User Story",
-    "hidden": false,
-    "properties": {
-      "color": "#F1ED92",
-      "description": "A functional requirement.",
-      "iconURL": "/polarion/icons/default/enums/type_userstory.gif"
-    },
-    "id": "userstory",
-    "default": true,
-    "enumId": "work-item-type",
-    "phantom": false
-  },
-  {
-    "sequenceNumber": 2,
-    "name": "Requirement",
-    "hidden": false,
-    "properties": {
-      "color": "#A280A9",
-      "description": "A nonfunctional requirement.",
-      "iconURL": "/polarion/icons/default/enums/type_requirement.gif"
-    },
-    "id": "requirement",
-    "default": false,
-    "enumId": "work-item-type",
-    "phantom": false
-  }
-]
-```
+This extension provides REST API. OpenAPI Specification can be obtained [here](docs/openapi.json).
 
-List of workItem fields for project and workitem type may be accessible using `/api/projects/{projectId}/workitem_types/{workItemType}/fields` endpoint.
-Request body example:
-
-```json
-[
-  "approvals",
-  "assignee",
-  "attachments",
-  "author",
-  "categories",
-  "comments"
-]
-```
-
-### Import file
-
-Import is accessible by posting a xlsx-file to the `/api/projects/{projectId}/import` endpoint.
-
-Response example:
-
-```json
-{
-  "updatedIds": [
-    "updated_id1",
-    "updated_id2"
-  ],
-  "createdIds": [
-    "created_id1",
-    "created_id2"
-  ],
-  "unchangedIds": [
-    "unchanged_id1",
-    "unchanged_id2"
-  ]
-}
-```
+## Known issues
 
+All good so far.