From 9511fae9d9471f533d3fc9c814bf2d5ac758d68f Mon Sep 17 00:00:00 2001 From: WintBit <68735689+WinterOfBit@users.noreply.github.com> Date: Fri, 7 Jul 2023 14:28:10 +0800 Subject: [PATCH] docs: add swagger docs for Resource-API (#2044) swagger files are all auto generated. --- controllers/resource.go | 33 ++++- swagger/swagger.json | 298 ++++++++++++++++++++++++++++++++++++++-- swagger/swagger.yml | 192 +++++++++++++++++++++++++- 3 files changed, 507 insertions(+), 16 deletions(-) diff --git a/controllers/resource.go b/controllers/resource.go index 5156ae9a..5ac8d51b 100644 --- a/controllers/resource.go +++ b/controllers/resource.go @@ -29,9 +29,19 @@ import ( ) // GetResources -// @router /get-resources [get] // @Tag Resource API // @Title GetResources +// @Description get resources +// @Param owner query string true "Owner" +// @Param user query string true "User" +// @Param pageSize query integer false "Page Size" +// @Param p query integer false "Page Number" +// @Param field query string false "Field" +// @Param value query string false "Value" +// @Param sortField query string false "Sort Field" +// @Param sortOrder query string false "Sort Order" +// @Success 200 {array} object.Resource The Response object +// @router /get-resources [get] func (c *ApiController) GetResources() { owner := c.Input().Get("owner") user := c.Input().Get("user") @@ -81,6 +91,9 @@ func (c *ApiController) GetResources() { // GetResource // @Tag Resource API // @Title GetResource +// @Description get resource +// @Param id query string true "The id ( owner/name ) of resource" +// @Success 200 {object} object.Resource The Response object // @router /get-resource [get] func (c *ApiController) GetResource() { id := c.Input().Get("id") @@ -98,6 +111,10 @@ func (c *ApiController) GetResource() { // UpdateResource // @Tag Resource API // @Title UpdateResource +// @Description get resource +// @Param id query string true "The id ( owner/name ) of resource" +// @Param resource body object.Resource true "The resource object" +// @Success 200 {object} controllers.Response Success or error // @router /update-resource [post] func (c *ApiController) UpdateResource() { id := c.Input().Get("id") @@ -116,6 +133,8 @@ func (c *ApiController) UpdateResource() { // AddResource // @Tag Resource API // @Title AddResource +// @Param resource body object.Resource true "Resource object" +// @Success 200 {object} controllers.Response Success or error // @router /add-resource [post] func (c *ApiController) AddResource() { var resource object.Resource @@ -132,6 +151,8 @@ func (c *ApiController) AddResource() { // DeleteResource // @Tag Resource API // @Title DeleteResource +// @Param resource body object.Resource true "Resource object" +// @Success 200 {object} controllers.Response Success or error // @router /delete-resource [post] func (c *ApiController) DeleteResource() { var resource object.Resource @@ -160,6 +181,16 @@ func (c *ApiController) DeleteResource() { // UploadResource // @Tag Resource API // @Title UploadResource +// @Param owner query string true "Owner" +// @Param user query string true "User" +// @Param application query string true "Application" +// @Param tag query string false "Tag" +// @Param parent query string false "Parent" +// @Param fullFilePath query string true "Full File Path" +// @Param createdTime query string false "Created Time" +// @Param description query string false "Description" +// @Param file formData file true "Resource file" +// @Success 200 {object} object.Resource FileUrl, objectKey // @router /upload-resource [post] func (c *ApiController) UploadResource() { owner := c.Input().Get("owner") diff --git a/swagger/swagger.json b/swagger/swagger.json index d20ddb91..c5ebc6d0 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -476,7 +476,26 @@ "tags": [ "Resource API" ], - "operationId": "ApiController.AddResource" + "operationId": "ApiController.AddResource", + "parameters": [ + { + "in": "body", + "name": "resource", + "description": "Resource object", + "required": true, + "schema": { + "$ref": "#/definitions/object.Resource" + } + } + ], + "responses": { + "200": { + "description": "Success or error", + "schema": { + "$ref": "#/definitions/controllers.Response" + } + } + } } }, "/api/add-role": { @@ -1344,7 +1363,26 @@ "tags": [ "Resource API" ], - "operationId": "ApiController.DeleteResource" + "operationId": "ApiController.DeleteResource", + "parameters": [ + { + "in": "body", + "name": "resource", + "description": "Resource object", + "required": true, + "schema": { + "$ref": "#/definitions/object.Resource" + } + } + ], + "responses": { + "200": { + "description": "Success or error", + "schema": { + "$ref": "#/definitions/controllers.Response" + } + } + } } }, "/api/delete-role": { @@ -2797,7 +2835,25 @@ "tags": [ "Resource API" ], - "operationId": "ApiController.GetResource" + "description": "get resource", + "operationId": "ApiController.GetResource", + "parameters": [ + { + "in": "query", + "name": "id", + "description": "The id ( owner/name ) of resource", + "required": true, + "type": "string" + } + ], + "responses": { + "200": { + "description": "The Response object", + "schema": { + "$ref": "#/definitions/object.Resource" + } + } + } } }, "/api/get-resources": { @@ -2805,7 +2861,71 @@ "tags": [ "Resource API" ], - "operationId": "ApiController.GetResources" + "description": "get resources", + "operationId": "ApiController.GetResources", + "parameters": [ + { + "in": "query", + "name": "owner", + "description": "Owner", + "required": true, + "type": "string" + }, + { + "in": "query", + "name": "user", + "description": "User", + "required": true, + "type": "string" + }, + { + "in": "query", + "name": "pageSize", + "description": "Page Size", + "type": "integer" + }, + { + "in": "query", + "name": "p", + "description": "Page Number", + "type": "integer" + }, + { + "in": "query", + "name": "field", + "description": "Field", + "type": "string" + }, + { + "in": "query", + "name": "value", + "description": "Value", + "type": "string" + }, + { + "in": "query", + "name": "sortField", + "description": "Sort Field", + "type": "string" + }, + { + "in": "query", + "name": "sortOrder", + "description": "Sort Order", + "type": "string" + } + ], + "responses": { + "200": { + "description": "The Response object", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/object.Resource" + } + } + } + } } }, "/api/get-role": { @@ -4532,7 +4652,34 @@ "tags": [ "Resource API" ], - "operationId": "ApiController.UpdateResource" + "description": "get resource", + "operationId": "ApiController.UpdateResource", + "parameters": [ + { + "in": "query", + "name": "id", + "description": "The id ( owner/name ) of resource", + "required": true, + "type": "string" + }, + { + "in": "body", + "name": "resource", + "description": "The resource object", + "required": true, + "schema": { + "$ref": "#/definitions/object.Resource" + } + } + ], + "responses": { + "200": { + "description": "Success or error", + "schema": { + "$ref": "#/definitions/controllers.Response" + } + } + } } }, "/api/update-role": { @@ -4779,7 +4926,76 @@ "tags": [ "Resource API" ], - "operationId": "ApiController.UploadResource" + "operationId": "ApiController.UploadResource", + "parameters": [ + { + "in": "query", + "name": "owner", + "description": "Owner", + "required": true, + "type": "string" + }, + { + "in": "query", + "name": "user", + "description": "User", + "required": true, + "type": "string" + }, + { + "in": "query", + "name": "application", + "description": "Application", + "required": true, + "type": "string" + }, + { + "in": "query", + "name": "tag", + "description": "Tag", + "type": "string" + }, + { + "in": "query", + "name": "parent", + "description": "Parent", + "type": "string" + }, + { + "in": "query", + "name": "fullFilePath", + "description": "Full File Path", + "required": true, + "type": "string" + }, + { + "in": "query", + "name": "createdTime", + "description": "Created Time", + "type": "string" + }, + { + "in": "query", + "name": "description", + "description": "Description", + "type": "string" + }, + { + "in": "formData", + "name": "file", + "description": "Resource file", + "required": true, + "type": "file" + } + ], + "responses": { + "200": { + "description": "FileUrl, objectKey", + "schema": { + "$ref": "#/definitions/object.Resource" + } + } + } } }, "/api/user": { @@ -4974,13 +5190,13 @@ "properties": { "data": { "additionalProperties": { - "description": "support string | class | List\u003cclass\u003e and os on", + "description": "support string, struct or []struct", "type": "string" } }, "data2": { "additionalProperties": { - "description": "support string | class | List\u003cclass\u003e and os on", + "description": "support string, struct or []struct", "type": "string" } }, @@ -5196,6 +5412,12 @@ "signupUrl": { "type": "string" }, + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, "termsOfUse": { "type": "string" }, @@ -6126,9 +6348,6 @@ "customLogo": { "type": "string" }, - "scopes": { - "type": "string" - }, "customTokenUrl": { "type": "string" }, @@ -6190,6 +6409,9 @@ "regionId": { "type": "string" }, + "scopes": { + "type": "string" + }, "signName": { "type": "string" }, @@ -6204,6 +6426,11 @@ }, "type": { "type": "string" + }, + "userMapping": { + "additionalProperties": { + "type": "string" + } } } }, @@ -6286,6 +6513,55 @@ } } }, + "object.Resource": { + "title": "Resource", + "type": "object", + "properties": { + "application": { + "type": "string" + }, + "createdTime": { + "type": "string" + }, + "description": { + "type": "string" + }, + "fileFormat": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "fileSize": { + "type": "integer", + "format": "int64" + }, + "fileType": { + "type": "string" + }, + "name": { + "type": "string" + }, + "owner": { + "type": "string" + }, + "parent": { + "type": "string" + }, + "provider": { + "type": "string" + }, + "tag": { + "type": "string" + }, + "url": { + "type": "string" + }, + "user": { + "type": "string" + } + } + }, "object.Role": { "title": "Role", "type": "object", diff --git a/swagger/swagger.yml b/swagger/swagger.yml index 31d9623a..54bb825b 100644 --- a/swagger/swagger.yml +++ b/swagger/swagger.yml @@ -308,6 +308,18 @@ paths: tags: - Resource API operationId: ApiController.AddResource + parameters: + - in: body + name: resource + description: Resource object + required: true + schema: + $ref: '#/definitions/object.Resource' + responses: + "200": + description: Success or error + schema: + $ref: '#/definitions/controllers.Response' /api/add-role: post: tags: @@ -869,6 +881,18 @@ paths: tags: - Resource API operationId: ApiController.DeleteResource + parameters: + - in: body + name: resource + description: Resource object + required: true + schema: + $ref: '#/definitions/object.Resource' + responses: + "200": + description: Success or error + schema: + $ref: '#/definitions/controllers.Response' /api/delete-role: post: tags: @@ -1818,12 +1842,67 @@ paths: get: tags: - Resource API + description: get resource operationId: ApiController.GetResource + parameters: + - in: query + name: id + description: The id ( owner/name ) of resource + required: true + type: string + responses: + "200": + description: The Response object + schema: + $ref: '#/definitions/object.Resource' /api/get-resources: get: tags: - Resource API + description: get resources operationId: ApiController.GetResources + parameters: + - in: query + name: owner + description: Owner + required: true + type: string + - in: query + name: user + description: User + required: true + type: string + - in: query + name: pageSize + description: Page Size + type: integer + - in: query + name: p + description: Page Number + type: integer + - in: query + name: field + description: Field + type: string + - in: query + name: value + description: Value + type: string + - in: query + name: sortField + description: Sort Field + type: string + - in: query + name: sortOrder + description: Sort Order + type: string + responses: + "200": + description: The Response object + schema: + type: array + items: + $ref: '#/definitions/object.Resource' /api/get-role: get: tags: @@ -2960,7 +3039,25 @@ paths: post: tags: - Resource API + description: get resource operationId: ApiController.UpdateResource + parameters: + - in: query + name: id + description: The id ( owner/name ) of resource + required: true + type: string + - in: body + name: resource + description: The resource object + required: true + schema: + $ref: '#/definitions/object.Resource' + responses: + "200": + description: Success or error + schema: + $ref: '#/definitions/controllers.Response' /api/update-role: post: tags: @@ -3123,6 +3220,53 @@ paths: tags: - Resource API operationId: ApiController.UploadResource + parameters: + - in: query + name: owner + description: Owner + required: true + type: string + - in: query + name: user + description: User + required: true + type: string + - in: query + name: application + description: Application + required: true + type: string + - in: query + name: tag + description: Tag + type: string + - in: query + name: parent + description: Parent + type: string + - in: query + name: fullFilePath + description: Full File Path + required: true + type: string + - in: query + name: createdTime + description: Created Time + type: string + - in: query + name: description + description: Description + type: string + - in: formData + name: file + description: Resource file + required: true + type: file + responses: + "200": + description: FileUrl, objectKey + schema: + $ref: '#/definitions/object.Resource' /api/user: get: tags: @@ -3251,11 +3395,11 @@ definitions: properties: data: additionalProperties: - description: support string | class | List and os on + description: support string, struct or []struct type: string data2: additionalProperties: - description: support string | class | List and os on + description: support string, struct or []struct type: string msg: type: string @@ -3400,6 +3544,10 @@ definitions: $ref: '#/definitions/object.SignupItem' signupUrl: type: string + tags: + type: array + items: + type: string termsOfUse: type: string themeData: @@ -4026,8 +4174,6 @@ definitions: type: string customLogo: type: string - scopes: - type: string customTokenUrl: type: string customUserInfoUrl: @@ -4069,6 +4215,8 @@ definitions: type: string regionId: type: string + scopes: + type: string signName: type: string subType: @@ -4079,6 +4227,9 @@ definitions: type: string type: type: string + userMapping: + additionalProperties: + type: string object.ProviderItem: title: ProviderItem type: object @@ -4132,6 +4283,39 @@ definitions: type: string user: type: string + object.Resource: + title: Resource + type: object + properties: + application: + type: string + createdTime: + type: string + description: + type: string + fileFormat: + type: string + fileName: + type: string + fileSize: + type: integer + format: int64 + fileType: + type: string + name: + type: string + owner: + type: string + parent: + type: string + provider: + type: string + tag: + type: string + url: + type: string + user: + type: string object.Role: title: Role type: object