You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@devlake.apache.org by zh...@apache.org on 2022/07/12 05:54:36 UTC
[incubator-devlake] branch main updated: feat: add ae swagger support (#2451)
This is an automated email from the ASF dual-hosted git repository.
zhangliang2022 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake.git
The following commit(s) were added to refs/heads/main by this push:
new ca8ede7f feat: add ae swagger support (#2451)
ca8ede7f is described below
commit ca8ede7f409cf8659b4e0e5f9f4e1be19e59bb18
Author: Klesh Wong <zh...@merico.dev>
AuthorDate: Tue Jul 12 13:54:32 2022 +0800
feat: add ae swagger support (#2451)
* feat: add ae swagger support
* fix: add asf header
---
.gitignore | 3 +-
Makefile | 7 +-
api/docs/docs.go | 683 -------------------------------------------
api/docs/stub.go | 18 ++
plugins/ae/api/connection.go | 63 ++--
plugins/ae/impl/impl.go | 2 +-
6 files changed, 72 insertions(+), 704 deletions(-)
diff --git a/.gitignore b/.gitignore
index 408e6e1a..82318dec 100644
--- a/.gitignore
+++ b/.gitignore
@@ -152,5 +152,6 @@ libgit2
api/docs/swagger.json
api/docs/swagger.yaml
-# mocks
+# auto generated code
mocks/
+api/docs/docs.go
diff --git a/Makefile b/Makefile
index c8abaaf0..7fc86054 100644
--- a/Makefile
+++ b/Makefile
@@ -43,7 +43,12 @@ run:
worker:
go run worker/*.go
-dev: build-plugin run
+swag:
+ echo "you need to install swag by `go install github.com/swaggo/swag/cmd/swag@latest` first"
+ swag init --parseDependency --parseInternal -o ./api/docs -g ./api/api.go -g plugins/*/api/*.go
+ echo "visit the swagger document on http://localhost:8080/swagger/index.html"
+
+dev: build-plugin swag run
debug: build-plugin-debug
dlv debug main.go
diff --git a/api/docs/docs.go b/api/docs/docs.go
deleted file mode 100644
index 56037bac..00000000
--- a/api/docs/docs.go
+++ /dev/null
@@ -1,683 +0,0 @@
-/*
-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.
-*/
-
-// Package docs GENERATED BY SWAG; DO NOT EDIT
-// This file was generated by swaggo/swag
-package docs
-
-import "github.com/swaggo/swag"
-
-const docTemplate = `{
- "schemes": {{ marshal .Schemes }},
- "swagger": "2.0",
- "info": {
- "description": "{{escape .Description}}",
- "title": "{{.Title}}",
- "contact": {},
- "license": {
- "name": "Apache-2.0"
- },
- "version": "{{.Version}}"
- },
- "host": "{{.Host}}",
- "basePath": "{{.BasePath}}",
- "paths": {
- "/blueprints": {
- "get": {
- "description": "get blueprints",
- "consumes": [
- "application/json"
- ],
- "tags": [
- "Blueprints"
- ],
- "summary": "get blueprints",
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "$ref": "#/definitions/gin.H"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- },
- "post": {
- "description": "post blueprints",
- "consumes": [
- "application/json"
- ],
- "tags": [
- "Blueprints"
- ],
- "summary": "post blueprints",
- "parameters": [
- {
- "description": "json",
- "name": "blueprint",
- "in": "body",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "$ref": "#/definitions/models.Blueprint"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- }
- },
- "/blueprints/{blueprintId}": {
- "get": {
- "description": "get blueprints",
- "consumes": [
- "application/json"
- ],
- "tags": [
- "Blueprints"
- ],
- "summary": "get blueprints",
- "parameters": [
- {
- "type": "integer",
- "description": "blueprint id",
- "name": "blueprintId",
- "in": "path",
- "required": true
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "$ref": "#/definitions/models.Blueprint"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- },
- "delete": {
- "description": "Delete BluePrints",
- "tags": [
- "Blueprints"
- ],
- "summary": "delete blueprints",
- "parameters": [
- {
- "type": "string",
- "description": "blueprintId",
- "name": "blueprintId",
- "in": "path",
- "required": true
- }
- ],
- "responses": {
- "200": {
- "description": ""
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- },
- "patch": {
- "description": "patch blueprints",
- "consumes": [
- "application/json"
- ],
- "tags": [
- "Blueprints"
- ],
- "summary": "patch blueprints",
- "parameters": [
- {
- "type": "string",
- "description": "blueprintId",
- "name": "blueprintId",
- "in": "path",
- "required": true
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "$ref": "#/definitions/models.Blueprint"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- }
- },
- "/domainlayer/repos": {
- "get": {
- "description": "Get all repos from database",
- "consumes": [
- "application/json"
- ],
- "tags": [
- "Domainlayer"
- ],
- "summary": "Get all repos from database",
- "responses": {
- "200": {
- "description": "{\"repos\": repos, \"count\": count}",
- "schema": {
- "$ref": "#/definitions/gin.H"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- }
- },
- "/ping": {
- "get": {
- "description": "check http status",
- "tags": [
- "Ping"
- ],
- "summary": "Ping",
- "responses": {
- "200": {
- "description": ""
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- }
- },
- "/pipelines": {
- "get": {
- "description": "GET /pipelines?status=TASK_RUNNING\u0026pending=1\u0026page=1\u0026pagesize=10\nRETURN SAMPLE\n{\n\"pipelines\": [\n{\"id\": 1, \"name\": \"test-pipeline\", ...}\n],\n\"count\": 5\n}",
- "tags": [
- "pipelines"
- ],
- "summary": "Get list of pipelines",
- "parameters": [
- {
- "type": "string",
- "description": "query",
- "name": "status",
- "in": "query",
- "required": true
- },
- {
- "type": "integer",
- "description": "query",
- "name": "pending",
- "in": "query",
- "required": true
- },
- {
- "type": "integer",
- "description": "query",
- "name": "page",
- "in": "query",
- "required": true
- },
- {
- "type": "integer",
- "description": "query",
- "name": "pagesize",
- "in": "query",
- "required": true
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "$ref": "#/definitions/models.Pipeline"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- },
- "post": {
- "description": "Create and run a new pipeline\nRETURN SAMPLE\n{\n\"name\": \"name-of-pipeline\",\n\"tasks\": [\n[ {\"plugin\": \"gitlab\", ...}, {\"plugin\": \"jira\"} ],\n[ {\"plugin\": \"github\", ...}],\n]\n}",
- "consumes": [
- "application/json"
- ],
- "tags": [
- "pipelines"
- ],
- "summary": "Create and run a new pipeline",
- "parameters": [
- {
- "description": "json",
- "name": "pipeline",
- "in": "body",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "$ref": "#/definitions/models.Pipeline"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- }
- },
- "/pipelines/{pipelineId}": {
- "get": {
- "description": "GET /pipelines/:pipelineId\nRETURN SAMPLE\n{\n\"id\": 1,\n\"name\": \"test-pipeline\",\n...\n}",
- "tags": [
- "pipelines"
- ],
- "parameters": [
- {
- "type": "integer",
- "description": "query",
- "name": "pipelineId",
- "in": "path",
- "required": true
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "$ref": "#/definitions/models.Pipeline"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- },
- "delete": {
- "description": "Cancel a pending pipeline",
- "tags": [
- "pipelines"
- ],
- "parameters": [
- {
- "type": "integer",
- "description": "pipeline ID",
- "name": "pipelineId",
- "in": "path",
- "required": true
- }
- ],
- "responses": {
- "200": {
- "description": ""
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- }
- },
- "/pipelines/{pipelineId}/tasks": {
- "get": {
- "description": "get task\nSAMPLE\n{\n\"tasks\": [\n{\"id\": 1, \"plugin\": \"\", ...}\n],\n\"count\": 5\n}",
- "consumes": [
- "application/json"
- ],
- "tags": [
- "task"
- ],
- "summary": "Get task",
- "parameters": [
- {
- "type": "integer",
- "description": "pipelineId",
- "name": "pipelineId",
- "in": "path",
- "required": true
- }
- ],
- "responses": {
- "200": {
- "description": "{\"tasks\": tasks, \"count\": count}",
- "schema": {
- "type": "string"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- }
- },
- "/push/{tableName}": {
- "post": {
- "description": "POST /push/:tableName",
- "consumes": [
- "application/json"
- ],
- "tags": [
- "push"
- ],
- "summary": "POST /push/:tableName",
- "parameters": [
- {
- "type": "string",
- "description": "table name",
- "name": "tableName",
- "in": "path",
- "required": true
- },
- {
- "description": "data",
- "name": "data",
- "in": "body",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "{\"rowsAffected\": rowsAffected}",
- "schema": {
- "$ref": "#/definitions/gin.H"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- }
- },
- "/version": {
- "get": {
- "description": "return a object",
- "consumes": [
- "application/json"
- ],
- "tags": [
- "version"
- ],
- "summary": "Get the version of lake",
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "type": "string"
- }
- },
- "400": {
- "description": "Bad Request",
- "schema": {
- "type": "string"
- }
- },
- "500": {
- "description": "Internel Error",
- "schema": {
- "type": "string"
- }
- }
- }
- }
- }
- },
- "definitions": {
- "gin.H": {
- "type": "object",
- "additionalProperties": true
- },
- "models.Blueprint": {
- "type": "object",
- "required": [
- "cronConfig",
- "name",
- "tasks"
- ],
- "properties": {
- "createdAt": {
- "type": "string"
- },
- "cronConfig": {
- "type": "string"
- },
- "enable": {
- "type": "boolean"
- },
- "id": {
- "type": "integer"
- },
- "name": {
- "type": "string"
- },
- "tasks": {
- "type": "array",
- "items": {
- "type": "integer"
- }
- },
- "updatedAt": {
- "type": "string"
- }
- }
- },
- "models.Pipeline": {
- "type": "object",
- "properties": {
- "beganAt": {
- "type": "string"
- },
- "blueprintId": {
- "type": "integer"
- },
- "createdAt": {
- "type": "string"
- },
- "finishedAt": {
- "type": "string"
- },
- "finishedTasks": {
- "description": "Deprecated",
- "type": "integer"
- },
- "id": {
- "type": "integer"
- },
- "message": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "spentSeconds": {
- "type": "integer"
- },
- "stage": {
- "type": "integer"
- },
- "status": {
- "type": "string"
- },
- "tasks": {
- "type": "array",
- "items": {
- "type": "integer"
- }
- },
- "totalTasks": {
- "type": "integer"
- },
- "updatedAt": {
- "type": "string"
- }
- }
- }
- }
-}`
-
-// SwaggerInfo holds exported Swagger Info so clients can modify it
-var SwaggerInfo = &swag.Spec{
- Version: "0.1",
- Host: "localhost:8080",
- BasePath: "/",
- Schemes: []string{},
- Title: "DevLake Swagger API",
- Description: "<h2>This is the main page of devlake api</h2>",
- InfoInstanceName: "swagger",
- SwaggerTemplate: docTemplate,
-}
-
-func init() {
- swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
-}
diff --git a/api/docs/stub.go b/api/docs/stub.go
new file mode 100644
index 00000000..079d819f
--- /dev/null
+++ b/api/docs/stub.go
@@ -0,0 +1,18 @@
+/*
+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.
+*/
+
+package docs
diff --git a/plugins/ae/api/connection.go b/plugins/ae/api/connection.go
index 52fe2819..b0bca088 100644
--- a/plugins/ae/api/connection.go
+++ b/plugins/ae/api/connection.go
@@ -33,9 +33,14 @@ type ApiMeResponse struct {
Name string `json:"name"`
}
-/*
-GET /plugins/ae/test/
-*/
+// @Summary test ae connection
+// @Description Test AE Connection
+// @Tags plugins/AE
+// @Param body body models.TestConnectionRequest true "json body"
+// @Success 200
+// @Failure 400 {string} errcode.Error "Bad Request"
+// @Failure 500 {string} errcode.Error "Internel Error"
+// @Router /plugins/ae/test [POST]
func TestConnection(input *core.ApiResourceInput) (*core.ApiResourceOutput, error) {
// decode
var err error
@@ -85,9 +90,14 @@ func TestConnection(input *core.ApiResourceInput) (*core.ApiResourceOutput, erro
}
}
-/*
-POST /plugins/ae/connections
-*/
+// @Summary create ae connection
+// @Description Create AE connection
+// @Tags plugins/AE
+// @Param body body models.AeConnection true "json body"
+// @Success 200
+// @Failure 400 {string} errcode.Error "Bad Request"
+// @Failure 500 {string} errcode.Error "Internel Error"
+// @Router /plugins/ae/connections [POST]
func PostConnections(input *core.ApiResourceInput) (*core.ApiResourceOutput, error) {
connection := &models.AeConnection{}
err := connectionHelper.Create(connection, input)
@@ -97,9 +107,13 @@ func PostConnections(input *core.ApiResourceInput) (*core.ApiResourceOutput, err
return &core.ApiResourceOutput{Body: connection, Status: http.StatusOK}, nil
}
-/*
-GET /plugins/ae/connections
-*/
+// @Summary get all ae connections
+// @Description Get all AE connections
+// @Tags plugins/AE
+// @Success 200
+// @Failure 400 {string} errcode.Error "Bad Request"
+// @Failure 500 {string} errcode.Error "Internel Error"
+// @Router /plugins/ae/connections [GET]
func ListConnections(input *core.ApiResourceInput) (*core.ApiResourceOutput, error) {
var connections []models.AeConnection
err := connectionHelper.List(&connections)
@@ -109,18 +123,27 @@ func ListConnections(input *core.ApiResourceInput) (*core.ApiResourceOutput, err
return &core.ApiResourceOutput{Body: connections, Status: http.StatusOK}, nil
}
-/*
-GET /plugins/ae/connections/:connectionId
-*/
+// @Summary get ae connection detail
+// @Description Get AE connection detail
+// @Tags plugins/AE
+// @Success 200
+// @Failure 400 {string} errcode.Error "Bad Request"
+// @Failure 500 {string} errcode.Error "Internel Error"
+// @Router /plugins/ae/connections/{connectionId} [GET]
func GetConnection(input *core.ApiResourceInput) (*core.ApiResourceOutput, error) {
connection := &models.AeConnection{}
err := connectionHelper.First(connection, input.Params)
return &core.ApiResourceOutput{Body: connection}, err
}
-/*
-PATCH /plugins/ae/connections/:connectionId
-*/
+// @Summary patch ae connection
+// @Description Patch AE connection
+// @Tags plugins/AE
+// @Param body body models.AeConnection true "json body"
+// @Success 200
+// @Failure 400 {string} errcode.Error "Bad Request"
+// @Failure 500 {string} errcode.Error "Internel Error"
+// @Router /plugins/ae/connections/{connectionId} [PATCH]
func PatchConnection(input *core.ApiResourceInput) (*core.ApiResourceOutput, error) {
connection := &models.AeConnection{}
err := connectionHelper.Patch(connection, input)
@@ -130,9 +153,13 @@ func PatchConnection(input *core.ApiResourceInput) (*core.ApiResourceOutput, err
return &core.ApiResourceOutput{Body: connection, Status: http.StatusOK}, nil
}
-/*
-DELETE /plugins/ae/connections/:connectionId
-*/
+// @Summary delete a ae connection
+// @Description Delete a AE connection
+// @Tags plugins/AE
+// @Success 200
+// @Failure 400 {string} errcode.Error "Bad Request"
+// @Failure 500 {string} errcode.Error "Internel Error"
+// @Router /plugins/ae/connections/{connectionId} [DELETE]
func DeleteConnection(input *core.ApiResourceInput) (*core.ApiResourceOutput, error) {
connection := &models.AeConnection{}
err := connectionHelper.First(connection, input.Params)
diff --git a/plugins/ae/impl/impl.go b/plugins/ae/impl/impl.go
index e567ecf3..e8f9c217 100644
--- a/plugins/ae/impl/impl.go
+++ b/plugins/ae/impl/impl.go
@@ -105,7 +105,7 @@ func (plugin AE) MigrationScripts() []migration.Script {
func (plugin AE) ApiResources() map[string]map[string]core.ApiResourceHandler {
return map[string]map[string]core.ApiResourceHandler{
"test": {
- "GET": api.TestConnection,
+ "POST": api.TestConnection,
},
"connections": {
"GET": api.ListConnections,