This is an automated email from the ASF dual-hosted git repository. linkinstar pushed a commit to branch dev in repository https://gitbox.apache.org/repos/asf/answer.git
commit d02d09bb9a80c74962cc6543320762d44a48253c Author: LinkinStars <[email protected]> AuthorDate: Tue Jun 24 11:06:14 2025 +0800 refactor(api): improve API documentation for Answer endpoints --- docs/docs.go | 254 ++++++++++++++++++++++++++++++++++++++++++++++++++---- docs/swagger.json | 254 ++++++++++++++++++++++++++++++++++++++++++++++++++---- docs/swagger.yaml | 178 ++++++++++++++++++++++++++++++++++---- 3 files changed, 638 insertions(+), 48 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 82ab3c77..31f36146 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -2134,7 +2134,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "api-answer" + "Answer" ], "summary": "Update Answer", "parameters": [ @@ -2163,7 +2163,7 @@ const docTemplate = `{ "ApiKeyAuth": [] } ], - "description": "Insert Answer", + "description": "add answer", "consumes": [ "application/json" ], @@ -2171,12 +2171,12 @@ const docTemplate = `{ "application/json" ], "tags": [ - "api-answer" + "Answer" ], - "summary": "Insert Answer", + "summary": "Add Answer", "parameters": [ { - "description": "AnswerAddReq", + "description": "add answer request", "name": "data", "in": "body", "required": true, @@ -2189,7 +2189,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "type": "string" + "$ref": "#/definitions/handler.RespBody" } } } @@ -2208,7 +2208,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "api-answer" + "Answer" ], "summary": "delete answer", "parameters": [ @@ -2247,7 +2247,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "api-answer" + "Answer" ], "summary": "Accepted", "parameters": [ @@ -2273,7 +2273,7 @@ const docTemplate = `{ }, "/answer/api/v1/answer/info": { "get": { - "description": "Get Answer", + "description": "Get Answer Detail", "consumes": [ "application/json" ], @@ -2281,14 +2281,13 @@ const docTemplate = `{ "application/json" ], "tags": [ - "api-answer" + "Answer" ], - "summary": "Get Answer", + "summary": "Get Answer Detail", "parameters": [ { "type": "string", - "default": "1", - "description": "Answer TagID", + "description": "id", "name": "id", "in": "query", "required": true @@ -2298,7 +2297,19 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "type": "string" + "allOf": [ + { + "$ref": "#/definitions/handler.RespBody" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/schema.GetAnswerInfoResp" + } + } + } + ] } } } @@ -2314,7 +2325,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "api-answer" + "Answer" ], "summary": "AnswerList", "parameters": [ @@ -2364,7 +2375,7 @@ const docTemplate = `{ "ApiKeyAuth": [] } ], - "description": "recover deleted answer", + "description": "recover the deleted answer", "consumes": [ "application/json" ], @@ -7992,6 +8003,60 @@ const docTemplate = `{ } } }, + "schema.AnswerInfo": { + "type": "object", + "properties": { + "accepted": { + "type": "integer" + }, + "collected": { + "type": "boolean" + }, + "content": { + "type": "string" + }, + "create_time": { + "type": "integer" + }, + "html": { + "type": "string" + }, + "id": { + "type": "string" + }, + "member_actions": { + "description": "MemberActions", + "type": "array", + "items": { + "$ref": "#/definitions/schema.PermissionMemberAction" + } + }, + "question_id": { + "type": "string" + }, + "question_info": { + "$ref": "#/definitions/schema.QuestionInfoResp" + }, + "status": { + "type": "integer" + }, + "update_time": { + "type": "integer" + }, + "update_user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "vote_count": { + "type": "integer" + }, + "vote_status": { + "type": "string" + } + } + }, "schema.AnswerUpdateReq": { "type": "object", "required": [ @@ -8352,6 +8417,17 @@ const docTemplate = `{ } } }, + "schema.GetAnswerInfoResp": { + "type": "object", + "properties": { + "info": { + "$ref": "#/definitions/schema.AnswerInfo" + }, + "question": { + "$ref": "#/definitions/schema.QuestionInfoResp" + } + } + }, "schema.GetBadgeInfoResp": { "type": "object", "properties": { @@ -9585,6 +9661,41 @@ const docTemplate = `{ } } }, + "schema.Operation": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "level": { + "$ref": "#/definitions/schema.OperationLevel" + }, + "msg": { + "type": "string" + }, + "time": { + "type": "integer" + }, + "type": { + "type": "string" + } + } + }, + "schema.OperationLevel": { + "type": "string", + "enum": [ + "info", + "danger", + "warning", + "secondary" + ], + "x-enum-varnames": [ + "OperationLevelInfo", + "OperationLevelDanger", + "OperationLevelWarning", + "OperationLevelSecondary" + ] + }, "schema.OperationQuestionReq": { "type": "object", "required": [ @@ -9738,6 +9849,117 @@ const docTemplate = `{ } } }, + "schema.QuestionInfoResp": { + "type": "object", + "properties": { + "accepted_answer_id": { + "type": "string" + }, + "answer_count": { + "type": "integer" + }, + "answered": { + "type": "boolean" + }, + "collected": { + "type": "boolean" + }, + "collection_count": { + "type": "integer" + }, + "content": { + "type": "string" + }, + "create_time": { + "type": "integer" + }, + "description": { + "type": "string" + }, + "edit_time": { + "type": "integer" + }, + "extends_actions": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.PermissionMemberAction" + } + }, + "first_answer_id": { + "type": "string" + }, + "follow_count": { + "type": "integer" + }, + "html": { + "type": "string" + }, + "id": { + "type": "string" + }, + "is_followed": { + "type": "boolean" + }, + "last_answer_id": { + "type": "string" + }, + "last_answered_user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "member_actions": { + "description": "MemberActions", + "type": "array", + "items": { + "$ref": "#/definitions/schema.PermissionMemberAction" + } + }, + "operation": { + "$ref": "#/definitions/schema.Operation" + }, + "pin": { + "type": "integer" + }, + "show": { + "type": "integer" + }, + "status": { + "type": "integer" + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.TagResp" + } + }, + "title": { + "type": "string" + }, + "unique_view_count": { + "type": "integer" + }, + "update_time": { + "type": "integer" + }, + "update_user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "url_title": { + "type": "string" + }, + "user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "view_count": { + "type": "integer" + }, + "vote_count": { + "type": "integer" + }, + "vote_status": { + "type": "string" + } + } + }, "schema.QuestionPageReq": { "type": "object", "properties": { diff --git a/docs/swagger.json b/docs/swagger.json index 689255a4..c2318a7c 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -2107,7 +2107,7 @@ "application/json" ], "tags": [ - "api-answer" + "Answer" ], "summary": "Update Answer", "parameters": [ @@ -2136,7 +2136,7 @@ "ApiKeyAuth": [] } ], - "description": "Insert Answer", + "description": "add answer", "consumes": [ "application/json" ], @@ -2144,12 +2144,12 @@ "application/json" ], "tags": [ - "api-answer" + "Answer" ], - "summary": "Insert Answer", + "summary": "Add Answer", "parameters": [ { - "description": "AnswerAddReq", + "description": "add answer request", "name": "data", "in": "body", "required": true, @@ -2162,7 +2162,7 @@ "200": { "description": "OK", "schema": { - "type": "string" + "$ref": "#/definitions/handler.RespBody" } } } @@ -2181,7 +2181,7 @@ "application/json" ], "tags": [ - "api-answer" + "Answer" ], "summary": "delete answer", "parameters": [ @@ -2220,7 +2220,7 @@ "application/json" ], "tags": [ - "api-answer" + "Answer" ], "summary": "Accepted", "parameters": [ @@ -2246,7 +2246,7 @@ }, "/answer/api/v1/answer/info": { "get": { - "description": "Get Answer", + "description": "Get Answer Detail", "consumes": [ "application/json" ], @@ -2254,14 +2254,13 @@ "application/json" ], "tags": [ - "api-answer" + "Answer" ], - "summary": "Get Answer", + "summary": "Get Answer Detail", "parameters": [ { "type": "string", - "default": "1", - "description": "Answer TagID", + "description": "id", "name": "id", "in": "query", "required": true @@ -2271,7 +2270,19 @@ "200": { "description": "OK", "schema": { - "type": "string" + "allOf": [ + { + "$ref": "#/definitions/handler.RespBody" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/schema.GetAnswerInfoResp" + } + } + } + ] } } } @@ -2287,7 +2298,7 @@ "application/json" ], "tags": [ - "api-answer" + "Answer" ], "summary": "AnswerList", "parameters": [ @@ -2337,7 +2348,7 @@ "ApiKeyAuth": [] } ], - "description": "recover deleted answer", + "description": "recover the deleted answer", "consumes": [ "application/json" ], @@ -7965,6 +7976,60 @@ } } }, + "schema.AnswerInfo": { + "type": "object", + "properties": { + "accepted": { + "type": "integer" + }, + "collected": { + "type": "boolean" + }, + "content": { + "type": "string" + }, + "create_time": { + "type": "integer" + }, + "html": { + "type": "string" + }, + "id": { + "type": "string" + }, + "member_actions": { + "description": "MemberActions", + "type": "array", + "items": { + "$ref": "#/definitions/schema.PermissionMemberAction" + } + }, + "question_id": { + "type": "string" + }, + "question_info": { + "$ref": "#/definitions/schema.QuestionInfoResp" + }, + "status": { + "type": "integer" + }, + "update_time": { + "type": "integer" + }, + "update_user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "vote_count": { + "type": "integer" + }, + "vote_status": { + "type": "string" + } + } + }, "schema.AnswerUpdateReq": { "type": "object", "required": [ @@ -8325,6 +8390,17 @@ } } }, + "schema.GetAnswerInfoResp": { + "type": "object", + "properties": { + "info": { + "$ref": "#/definitions/schema.AnswerInfo" + }, + "question": { + "$ref": "#/definitions/schema.QuestionInfoResp" + } + } + }, "schema.GetBadgeInfoResp": { "type": "object", "properties": { @@ -9558,6 +9634,41 @@ } } }, + "schema.Operation": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "level": { + "$ref": "#/definitions/schema.OperationLevel" + }, + "msg": { + "type": "string" + }, + "time": { + "type": "integer" + }, + "type": { + "type": "string" + } + } + }, + "schema.OperationLevel": { + "type": "string", + "enum": [ + "info", + "danger", + "warning", + "secondary" + ], + "x-enum-varnames": [ + "OperationLevelInfo", + "OperationLevelDanger", + "OperationLevelWarning", + "OperationLevelSecondary" + ] + }, "schema.OperationQuestionReq": { "type": "object", "required": [ @@ -9711,6 +9822,117 @@ } } }, + "schema.QuestionInfoResp": { + "type": "object", + "properties": { + "accepted_answer_id": { + "type": "string" + }, + "answer_count": { + "type": "integer" + }, + "answered": { + "type": "boolean" + }, + "collected": { + "type": "boolean" + }, + "collection_count": { + "type": "integer" + }, + "content": { + "type": "string" + }, + "create_time": { + "type": "integer" + }, + "description": { + "type": "string" + }, + "edit_time": { + "type": "integer" + }, + "extends_actions": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.PermissionMemberAction" + } + }, + "first_answer_id": { + "type": "string" + }, + "follow_count": { + "type": "integer" + }, + "html": { + "type": "string" + }, + "id": { + "type": "string" + }, + "is_followed": { + "type": "boolean" + }, + "last_answer_id": { + "type": "string" + }, + "last_answered_user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "member_actions": { + "description": "MemberActions", + "type": "array", + "items": { + "$ref": "#/definitions/schema.PermissionMemberAction" + } + }, + "operation": { + "$ref": "#/definitions/schema.Operation" + }, + "pin": { + "type": "integer" + }, + "show": { + "type": "integer" + }, + "status": { + "type": "integer" + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.TagResp" + } + }, + "title": { + "type": "string" + }, + "unique_view_count": { + "type": "integer" + }, + "update_time": { + "type": "integer" + }, + "update_user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "url_title": { + "type": "string" + }, + "user_info": { + "$ref": "#/definitions/schema.UserBasicInfo" + }, + "view_count": { + "type": "integer" + }, + "vote_count": { + "type": "integer" + }, + "vote_status": { + "type": "string" + } + } + }, "schema.QuestionPageReq": { "type": "object", "properties": { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index a399b3bf..f89ea946 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -349,6 +349,42 @@ definitions: required: - content type: object + schema.AnswerInfo: + properties: + accepted: + type: integer + collected: + type: boolean + content: + type: string + create_time: + type: integer + html: + type: string + id: + type: string + member_actions: + description: MemberActions + items: + $ref: '#/definitions/schema.PermissionMemberAction' + type: array + question_id: + type: string + question_info: + $ref: '#/definitions/schema.QuestionInfoResp' + status: + type: integer + update_time: + type: integer + update_user_info: + $ref: '#/definitions/schema.UserBasicInfo' + user_info: + $ref: '#/definitions/schema.UserBasicInfo' + vote_count: + type: integer + vote_status: + type: string + type: object schema.AnswerUpdateReq: properties: captcha_code: @@ -595,6 +631,13 @@ definitions: description: if user is followed object will be true,otherwise false type: boolean type: object + schema.GetAnswerInfoResp: + properties: + info: + $ref: '#/definitions/schema.AnswerInfo' + question: + $ref: '#/definitions/schema.QuestionInfoResp' + type: object schema.GetBadgeInfoResp: properties: award_count: @@ -1455,6 +1498,31 @@ definitions: toast_return_message: type: boolean type: object + schema.Operation: + properties: + description: + type: string + level: + $ref: '#/definitions/schema.OperationLevel' + msg: + type: string + time: + type: integer + type: + type: string + type: object + schema.OperationLevel: + enum: + - info + - danger + - warning + - secondary + type: string + x-enum-varnames: + - OperationLevelInfo + - OperationLevelDanger + - OperationLevelWarning + - OperationLevelSecondary schema.OperationQuestionReq: properties: id: @@ -1565,6 +1633,80 @@ definitions: - tags - title type: object + schema.QuestionInfoResp: + properties: + accepted_answer_id: + type: string + answer_count: + type: integer + answered: + type: boolean + collected: + type: boolean + collection_count: + type: integer + content: + type: string + create_time: + type: integer + description: + type: string + edit_time: + type: integer + extends_actions: + items: + $ref: '#/definitions/schema.PermissionMemberAction' + type: array + first_answer_id: + type: string + follow_count: + type: integer + html: + type: string + id: + type: string + is_followed: + type: boolean + last_answer_id: + type: string + last_answered_user_info: + $ref: '#/definitions/schema.UserBasicInfo' + member_actions: + description: MemberActions + items: + $ref: '#/definitions/schema.PermissionMemberAction' + type: array + operation: + $ref: '#/definitions/schema.Operation' + pin: + type: integer + show: + type: integer + status: + type: integer + tags: + items: + $ref: '#/definitions/schema.TagResp' + type: array + title: + type: string + unique_view_count: + type: integer + update_time: + type: integer + update_user_info: + $ref: '#/definitions/schema.UserBasicInfo' + url_title: + type: string + user_info: + $ref: '#/definitions/schema.UserBasicInfo' + view_count: + type: integer + vote_count: + type: integer + vote_status: + type: string + type: object schema.QuestionPageReq: properties: in_days: @@ -4263,13 +4405,13 @@ paths: - ApiKeyAuth: [] summary: delete answer tags: - - api-answer + - Answer post: consumes: - application/json - description: Insert Answer + description: add answer parameters: - - description: AnswerAddReq + - description: add answer request in: body name: data required: true @@ -4281,12 +4423,12 @@ paths: "200": description: OK schema: - type: string + $ref: '#/definitions/handler.RespBody' security: - ApiKeyAuth: [] - summary: Insert Answer + summary: Add Answer tags: - - api-answer + - Answer put: consumes: - application/json @@ -4309,7 +4451,7 @@ paths: - ApiKeyAuth: [] summary: Update Answer tags: - - api-answer + - Answer /answer/api/v1/answer/acceptance: post: consumes: @@ -4333,15 +4475,14 @@ paths: - ApiKeyAuth: [] summary: Accepted tags: - - api-answer + - Answer /answer/api/v1/answer/info: get: consumes: - application/json - description: Get Answer + description: Get Answer Detail parameters: - - default: "1" - description: Answer TagID + - description: id in: query name: id required: true @@ -4352,10 +4493,15 @@ paths: "200": description: OK schema: - type: string - summary: Get Answer + allOf: + - $ref: '#/definitions/handler.RespBody' + - properties: + data: + $ref: '#/definitions/schema.GetAnswerInfoResp' + type: object + summary: Get Answer Detail tags: - - api-answer + - Answer /answer/api/v1/answer/page: get: consumes: @@ -4391,12 +4537,12 @@ paths: type: string summary: AnswerList tags: - - api-answer + - Answer /answer/api/v1/answer/recover: post: consumes: - application/json - description: recover deleted answer + description: recover the deleted answer parameters: - description: answer in: body
