Merge pull request #22 from fossology/docs/api/swagger

doc(swagger): add Swagger doc for all endpoints and reorganize routing

Reviewed-by: [email protected], [email protected]

.github/workflows/api-swagger.yml

@@ -0,0 +1,67 @@
+# SPDX-FileCopyrightText: 2023 Siemens AG
+# SPDX-FileContributor: Gaurav Mishra <[email protected]>
+# SPDX-License-Identifier: GPL-2.0-only
+
+name: Swagger API Updated
+
+on:
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+jobs:
+
+  doc-diff:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.20'
+        check-latest: true
+        cache: true
+
+    - name: Install swag
+      run: |
+        go install github.com/swaggo/swag/cmd/swag@latest
+
+    - name: Build Swagger documents
+      run: |
+        swag init --generalInfo api.go --dir ./pkg/api,./pkg/auth,./pkg/db,./pkg/models,./pkg/utils --output ./swag/docs
+
+    - name: Check doc diff
+      run: |
+        diff swag/docs/docs.go cmd/laas/docs/docs.go > swagger-diff.txt
+        # Check if file swagger-diff.txt is empty
+        if [ -s swagger-diff.txt ]
+        then
+          # If file is not empty, echo a message and exit 1
+          echo "Swagger docs are not up to date. Please run 'swag init' and commit the changes."
+          exit 1
+        fi
+
+  doc-fmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.20'
+          check-latest: true
+          cache: true
+
+      - name: Install swag
+        run: |
+          go install github.com/swaggo/swag/cmd/swag@latest
+
+      - name: Format Swagger documents
+        run: |
+          swag fmt --generalInfo ./pkg/api/api.go --dir ./pkg/api,./pkg/auth,./pkg/db,./pkg/models,./pkg/utils
+
+      - name: Check file diff
+        run: |
+          git diff --exit-code

.reuse/dep5

@@ -0,0 +1,9 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: LicenseDB
+Source: https://github.com/fossology/LicenseDB/
+Upstream-Contact: FOSSology <[email protected]>
+Disclaimer: <text> This file is offered as-is, without any warranty. </text>
+
+Files: cmd/laas/docs/*
+Copyright: Fossology contributors
+License: GPL-2.0-only

README.md

@@ -86,3 +86,19 @@ go build ./cmd/laas
 ```bash
 go run ./cmd/laas
 ```
+
+### Generating Swagger Documentation
+1. Install [swag](https://github.com/swaggo/swag) using the following command.
+    ```bash
+    go install github.com/swaggo/swag/cmd/swag@latest
+    ```
+2. Run the following command to generate swagger documentation.
+    ```bash
+    swag init --generalInfo api.go --dir ./pkg/api,./pkg/auth,./pkg/db,./pkg/models,./pkg/utils --output ./cmd/laas/docs
+    ```
+3. Swagger documentation will be generated in `./cmd/laas/docs` folder.
+4. Run the project and navigate to `http://localhost:8080/swagger/index.html` to view the documentation.
+5. Optionally, after changing any documentation comments, format them with following command.
+    ```bash
+    swag fmt --generalInfo ./pkg/api/api.go --dir ./pkg/api,./pkg/auth,./pkg/db,./pkg/models,./pkg/utils
+    ```