fix: swag doc 500 / PLUGIN option not working (apache#6353)

backend/Makefile

@@ -35,18 +35,7 @@ python-dep:
 dep: go-dep python-dep
 
 swag:
-	if [ -z $(PLUGIN) ]; then \
-		swag init --parseDependency --parseInternal -o ./server/api/docs -g ./server/api/api.go -g ./plugins/*/api/*.go; \
-	elif [ $(PLUGIN) = "none" ]; then \
-		swag init --parseDependency --parseInternal -o ./server/api/docs -g ./server/api/api.go;\
-	else \
-		plugins="";\
-		for p in $$(echo $(PLUGIN) | tr "," "\n"); do \
-			plugins="$$plugins -g ./plugins/$$p/api/*.go"; \
-		done;\
-		swag init --parseDependency --parseInternal -o ./server/api/docs -g ./server/api/api.go "$$plugins"; \
-	fi;\
-	echo "visit the swagger document on http://localhost:8080/swagger/index.html";
+	scripts/swag.sh
 
 build-plugin:
 	if [ "$(PLUGIN)" = "none" ]; then \

backend/plugins/gitlab/api/scope_api.go

@@ -81,7 +81,7 @@ func GetScopeList(input *plugin.ApiResourceInput) (*plugin.ApiResourceOutput, er
 // @Param scopeId path int false "project ID"
 // @Param pageSize query int false "page size, default 50"
 // @Param page query int false "page size, default 1"
-// @Success 200  {object} ScopeRes
+// @Success 200  {object} ScopeDetail
 // @Failure 400  {object} shared.ApiBody "Bad Request"
 // @Failure 500  {object} shared.ApiBody "Internal Error"
 // @Router /plugins/gitlab/connections/{connectionId}/scopes/{scopeId} [GET]

backend/plugins/webhook/api/connection.go

@@ -19,20 +19,21 @@ package api
 
 import (
 	"fmt"
+	"net/http"
+	"strconv"
+
 	"github.com/apache/incubator-devlake/core/dal"
 	"github.com/apache/incubator-devlake/core/errors"
 	coreModels "github.com/apache/incubator-devlake/core/models"
 	"github.com/apache/incubator-devlake/core/plugin"
 	"github.com/apache/incubator-devlake/plugins/webhook/models"
-	"net/http"
-	"strconv"
 )
 
 // PostConnections
 // @Summary create webhook connection
 // @Description Create webhook connection, example: {"name":"Webhook data connection name"}
 // @Tags plugins/webhook
-// @Param body body models.WebhookConnection true "json body"
+// @Param body body WebhookConnectionResponse true "json body"
 // @Success 200  {object} WebhookConnectionResponse
 // @Failure 400  {string} errcode.Error "Bad Request"
 // @Failure 500  {string} errcode.Error "Internal Error"
@@ -143,7 +144,7 @@ type WebhookConnectionResponse struct {
 // @Summary get all webhook connections
 // @Description Get all webhook connections
 // @Tags plugins/webhook
-// @Success 200  {object} []*WebhookConnectionResponse
+// @Success 200  {object} []WebhookConnectionResponse
 // @Failure 400  {string} errcode.Error "Bad Request"
 // @Failure 500  {string} errcode.Error "Internal Error"
 // @Router /plugins/webhook/connections [GET]

backend/scripts/swag.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -e
+
+ROOT_DIR=$(dirname $(dirname "$0"))
+
+echo $ROOT_DIR
+# generate all docs by default, set the working dir (-d .) to root and general api info file (-g ./server/api/api.go).
+DOC_DIRS=$ROOT_DIR
+GENERAL_API_INFO_PATH=$ROOT_DIR/server/api/api.go
+
+
+if [ -n "$DEVLAKE_PLUGINS" ]; then
+  # change doc dir to avoid generating all docs (-d ./server/api)
+  DOC_DIRS=$ROOT_DIR/server/api
+  GENERAL_API_INFO_PATH=api.go
+  if ! [ "$DEVLAKE_PLUGINS" = "none" ]; then
+    # append plugin dirs to the doc dirs
+    for plugin in $(echo $DEVLAKE_PLUGINS | tr "," "\n"); do
+      DOC_DIRS="$DOC_DIRS,$ROOT_DIR/plugins/$plugin"
+    done
+  fi
+fi
+
+swag init --parseDependency --parseInternal -o $DIR/server/api/docs -g $GENERAL_API_INFO_PATH -d $DOC_DIRS
+echo "visit the swagger document on http://localhost:8080/swagger/index.html";