Swagger workflow (#249)

* [Chore] Add swag fmt to `mage spec`

* Keep CI in sync with toolchain

* We're not going crazy

* Remove unnecessary installation

* typo

* moved spec step after git checkout

* Do not fetch history

* fetch - but without history

* setting ref

* Bump down checkout action

* v3 with repository

* changing the user

* use PAT for publish of swagger docs

* use publish action instead of script

* using a separate workflow

* pr trigger

* syntax

* helps to checkout the code

* simplify

* trying push

* checkout

* adding in github token reference

* trying the previoous approach with a twist

* push as script

* trying to push back to the repo

* set token like this

* set token

* set token

* set token

* expand variables helps

* using clone url

* push to HEAD

* cleaning up full url

* oh no now using sed

* giving up - this will generate doc if needed on push to main

Co-authored-by: Andres Uribe Gonzalez <[email protected]>
Co-authored-by: Andres Uribe <[email protected]>
Co-authored-by: Gabe <[email protected]>

.github/workflows/ci.yml

@@ -29,43 +29,6 @@ jobs:
       - name: Check Vulnerabilities
         run: mage -v vuln
 
-  generate-spec:
-    runs-on: ubuntu-latest
-    steps:
-    - name: fetch history
-      uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-
-    - name: Set up Go
-      uses: actions/setup-go@v3
-      with:
-        go-version: 1.19.4
-        cache: true
-
-    - name: Install Mage
-      run: go install github.com/magefile/mage
-
-    - name: Update to latest spec
-      shell: bash
-      run: |
-        export PATH=$PATH:$(go env GOPATH)/bin
-        go install github.com/swaggo/swag/cmd/[email protected]
-        mage spec
-
-    - name: Push generated spec file
-      uses: actions/checkout@v3
-    - run: |
-        git config --global user.name "${GITHUB_ACTOR}"
-        git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
-        if (git diff --shortstat | grep '[0-9]'); then \
-          git add .; \
-          git commit -m "gen OpenAPI Spec by github-actions"; \
-          git push
-        fi
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
   build:
     runs-on: ubuntu-latest
     steps:

.github/workflows/swagger-doc.yml

@@ -0,0 +1,41 @@
+name: swagger-doc
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+
+  generate-swagger:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Go
+      uses: actions/setup-go@v3
+      with:
+        go-version: 1.19.4
+        cache: true
+
+    - name: Install Mage
+      run: go install github.com/magefile/mage
+
+    - name: Update spec and push generated spec file
+      uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+        ref: ${{ github.event.pull_request.head.ref }}
+        repository: ${{ github.event.pull_request.head.repo.full_name }}
+    - run: |
+        export PATH=$PATH:$(go env GOPATH)/bin
+        mage spec
+        git config user.name github-actions
+        git config user.email [email protected]
+        if (git diff --shortstat | grep '[0-9]'); then \
+          git add .; \
+          git commit -m "gen OpenAPI Spec by github-actions"; \
+          git push
+        fi
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

magefile.go

@@ -108,7 +108,11 @@ func Integration() error {
 // Spec generates an OpenAPI spec yaml based on code annotations.
 func Spec() error {
 	swagCommand := "swag"
-	if err := installIfNotPresent(swagCommand, "github.com/swaggo/swag/cmd/swag@latest"); err != nil {
+	if err := installIfNotPresent(swagCommand, "github.com/swaggo/swag/cmd/[email protected]"); err != nil {
+		logrus.Fatal(err)
+		return err
+	}
+	if err := sh.Run(swagCommand, "fmt", "-d", "pkg/server/router"); err != nil {
 		logrus.Fatal(err)
 		return err
 	}

pkg/server/router/presentation.go

@@ -374,7 +374,7 @@ type ReviewSubmissionResponse struct {
 }
 
 // ReviewSubmission godoc
-// @Summary      Review a pending submissions
+// @Summary      Review a pending submission
 // @Description  Reviews a pending submission. After this method is called, the operation with `id==presentations/submissions/{submission_id}` will be updated with the result of this invocation.
 // @Tags         SubmissionAPI
 // @Accept       json