From 4024aa496241459f381df3b3efbb74ab2b12837d Mon Sep 17 00:00:00 2001 From: Jasder <2053003901@@qq.com> Date: Thu, 2 Jan 2020 11:56:55 +0800 Subject: [PATCH] Update api documents --- README.md | 511 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 364 insertions(+), 147 deletions(-) diff --git a/README.md b/README.md index 86dbefd0f..9b188c2fc 100644 --- a/README.md +++ b/README.md @@ -243,14 +243,13 @@ POST api/projects ``` curl -X POST \ -d "user_id=36401" \ --d "name=好项目" \ +-d "name=hnfl_demo" \ -d "description=my first project" \ --d "repository_name=gorails" \ +-d "repository_name=hnfl_demo" \ -d "project_category_id=1" \ -d "project_language_id=2" \ --d "ignore_id=2000" \ +-d "ignore_id=2" \ -d "license_id=1" \ --d "private=true" http://localhost:3000/api/projects/ | jq ``` *请求参数说明:* @@ -332,34 +331,23 @@ http://localhost:3000/api/projects/migrate | jq ``` --- -#### 项目详情 +#### 获取代码目录列表 ``` -POST api/projects/:identifier +POST api/:login/:repo_identifier/entries ``` *示例* ``` curl -X GET \ --d "user_id=36401" \ --d "clone_addr=https://gitea.com/CasperVector/slew.git" \ --d "name=ni项目" \ --d "description=my first project" \ --d "repository_name=mirror_demo" \ --d "project_category_id=1" \ --d "project_language_id=2" \ -http://localhost:3000/api/projects/migrate | jq +-d "ref=develop" \ +http://localhost:3000/api/18816895620/mirror_demo/entries | jq ``` *请求参数说明:* |参数名|必选|类型|说明| -|-|-|- -|user_id |是|int |用户id或者组织id | -|name |是|string |项目名称 | -|clone_addr |是|string |镜像项目clone地址 | -|description |否|string |项目描述 | -|repository_name |是|string |仓库名称, 只含有数字、字母、下划线不能以下划线开头和结尾，且唯一 | -|project_category_id|是|int |项目类别id | -|project_language_id|是|int |项目语言id | -|private |否|boolean|项目是否私有, true：为私有，false: 非私有，默认为公开 | +|login |是|string |用户标识(login) | +|repo_identifier |是|string |仓库标识(identifier) | +|ref |否|string |分支名称、tag名称或是提交记录id，默认为master分支 | *返回参数说明:* @@ -367,15 +355,127 @@ http://localhost:3000/api/projects/migrate | jq |参数名|类型|说明| -|-|- |id |int |id | -|name |string|项目名称| - +|name |string|文件夹或文件名称| +|path |string|文件夹或文件相对路径| +|type |string|文件类型， file:文件，dir：文件目录| +|size |int|文件夹或文件大小 单位KB| +|content |string|文件内容，| +|target |string|标签| 返回值 ``` +[ { - "id": 3263, - "name": "ni项目" + "name": "Manual", + "path": "Manual", + "sha": "c2f18765235076b4c835b3e31262b3ee65176a75", + "type": "file", + "size": 12579, + "content": null, + "target": null, + "commit": null +}, +{ + "name": "README", + "path": "README", + "sha": "91a29176828eba5c5598f5d4a95458e861f271ec", + "type": "file", + "size": 1767, + "content": null, + "target": null, + "commit": null +}, +{ + "name": "base", + "path": "base", + "sha": "7adbe5698e02dba062216333d5e1d16b36ae1cbd", + "type": "dir", + "size": 0, + "content": null, + "target": null, + "commit": null } +] +``` +--- + +#### 获取子目录代码列表 +``` +POST api/:login/:repo_identifier/sub_entries +``` +*示例* +``` +curl -X GET \ +-d "ref=develop" \ +-d "filepath=lib/slew.rc" \ +http://localhost:3000/api/18816895620/mirror_demo/sub_entries | jq +``` +*请求参数说明:* + +|参数名|必选|类型|说明| +-|-|-|- +|login |是|string |用户标识(login) | +|repo_identifier |是|string |仓库标识(identifier) | +|filepath |是|string |文件夹、文件路径 | +|ref |否|string |分支名称、tag名称或是提交记录id，默认为master分支 | + + +*返回参数说明:* + +|参数名|类型|说明| +-|-|- +|id |int |id | +|name |string|文件夹或文件名称| +|path |string|文件夹或文件相对路径| +|type |string|文件类型， file:文件，dir：文件目录| +|size |int|文件夹或文件大小 单位KB| +|content |string|文件内容，| +|target |string|标签| +|url |string|文件访问链接,带分支| +|html_url |string|文件访问链接，未标识分支| +|git_url |string|文件夹或文件的git仓库访问链接| +|download_url |string|文件下载、文件内容访问链接| + +返回值 +``` +[ + { + "name": "build.rc", + "path": "lib/build.rc", + "type": "", + "size": 1268, + "content": null, + "target": null, + "url": "http://localhost:3003/api/v1/repos/18816895620/mirror_demo/contents/lib/build.rc?ref=master", + "html_url": "http://localhost:3003/18816895620/mirror_demo/src/branch/master/lib/build.rc", + "git_url": "http://localhost:3003/api/v1/repos/18816895620/mirror_demo/git/blobs/191fcf1a63b3777e2977fcede7dd5309efdd70fe", + "download_url": null + }, + { + "name": "cfg.rc", + "path": "lib/cfg.rc", + "type": "file", + "size": 107, + "content": null, + "target": null, + "url": "http://localhost:3003/api/v1/repos/18816895620/mirror_demo/contents/lib/cfg.rc?ref=master", + "html_url": "http://localhost:3003/18816895620/mirror_demo/src/branch/master/lib/cfg.rc", + "git_url": "http://localhost:3003/api/v1/repos/18816895620/mirror_demo/git/blobs/0b91ba0ed1c00e130c77bb9058af3787fea986a0", + "download_url": "http://localhost:3003/18816895620/mirror_demo/raw/branch/master/lib/cfg.rc" + }, + { + "name": "fn", + "path": "lib/fn", + "type": "dir", + "size": 0, + "content": null, + "target": null, + "url": "http://localhost:3003/api/v1/repos/18816895620/mirror_demo/contents/lib/fn?ref=master", + "html_url": "http://localhost:3003/18816895620/mirror_demo/src/branch/master/lib/fn", + "git_url": "http://localhost:3003/api/v1/repos/18816895620/mirror_demo/git/blobs/e33bd45949ef8f804471d0b6b2c59728eb445989", + "download_url": null + } +] ``` --- @@ -473,7 +573,7 @@ http://localhost:3000/api/projects | jq |limit |否|string |每页多少条数据，默认15条 | |sort_by |否|string |排序类型, 取值：updated_on \| created_on \| forked_count \| praises_count, updated_on: 更新时间排序，created_on: 创建时间排序，forked_count: fork数据排序，praises_count: 点赞数量排序，默认为updated_on更新时间排序 | |sort_direction|否|string |排序方式,取值为: desc \| asc; desc: 降序排序， asc: 升序排序， 默认为：desc | -|name |否|string |项目名称, 按照项目名称搜索 | +|search |否|string |按照项目名称搜索 | |category_id |否|int |项目类别id | |language_id |否|int |项目语言id | |project_type |否|string |项目类型， 取值为：common \| mirror; common:开源托管项目, mirror:开源镜像项目 | @@ -483,134 +583,148 @@ http://localhost:3000/api/projects | jq |参数名|类型|说明| -|-|- -|id |string |项目标识 | -|name |string|项目名称| -|description |string|项目简介| -|visits |int|流量数| -|forked_count |int|被fork的数量| -|is_public |boolean|是否公开， true:公开，false:未公开| -|mirror_url |string|镜像url| -|last_update_time |int|最后更新时间，为UNIX格式的时间戳| -|author |object|项目创建者| -|-- name |string|用户名，也是用户标识| -|category |object|项目类别| +|total_count |int |项目总条数 | +|id |string |项目标识 | +|name |string|项目名称| +|description |string|项目简介| +|visits |int|流量数| +|forked_count |int|被fork的数量| +|praises_count |int|star数量| +|is_public |boolean|是否公开， true:公开，false:未公开| +|mirror_url |string|镜像url| +|last_update_time|int|最后更新时间，为UNIX格式的时间戳| +|author |object|项目创建者| +|-- name |string|用户名，也是用户标识| +|category |object|项目类别| |-- id |int|项目类型id| -|-- name |string|项目类型名称| -|language |object|项目语言| +|-- name |string|项目类型名称| +|language |object|项目语言| |-- id |int|项目语言id| -|-- name |string|项目语言名称| - +|-- name |string|项目语言名称| 返回值 ``` -[ - { - "id": "tongjj", - "name": "统计局", - "description": "my first project", - "visits": 0, - "forked_count": 0, - "is_public": true, - "mirror_url": null, - "last_update_time": 1577415173, - "author": { - "name": "18816895620" - }, - "category": { - "id": 1, - "name": "大数据" - }, - "language": { - "id": 2, - "name": "C" - } - }, - { - "id": null, - "name": "开源同名", - "description": "my first project", - "visits": 0, - "forked_count": 0, - "is_public": false, - "mirror_url": "https://gitea.com/CasperVector/slew.git", - "last_update_time": 1577346228, - "author": { - "name": "18816895620" - }, - "category": { - "id": 1, - "name": "大数据" - }, - "language": { - "id": 2, - "name": "C" - } - }, - { - "id": "mvp_demo", - "name": "开源支持", - "description": "my first project", - "visits": 0, - "forked_count": 0, - "is_public": true, - "mirror_url": null, - "last_update_time": 1577341572, - "author": { - "name": "18816895620" - }, - "category": { - "id": 1, - "name": "大数据" - }, - "language": { - "id": 2, - "name": "C" - } - }, - { - "id": null, - "name": "ni项目1", - "description": "my first project", - "visits": 0, - "forked_count": 0, - "is_public": true, - "mirror_url": "https://gitea.com/CasperVector/slew.git", - "last_update_time": 1577092908, - "author": { - "name": "18816895620" +{ + "total_count": 3096, + "projects": [ + { + "id": "hnfl_demo1", + "name": "hnfl_demo1", + "description": "my first project", + "visits": 0, + "praises_count": 0, + "forked_count": 0, + "is_public": true, + "mirror_url": null, + "last_update_time": 1577697461, + "author": { + "name": "18816895620", + "image_url": "avatars/User/b" + }, + "category": { + "id": 1, + "name": "大数据" + }, + "language": { + "id": 2, + "name": "C" + } }, - "category": { - "id": 1, - "name": "大数据" + { + "id": "hnfl_demo", + "name": "hnfl_demo", + "description": "my first project", + "visits": 0, + "praises_count": 0, + "forked_count": 0, + "is_public": true, + "mirror_url": null, + "last_update_time": 1577697403, + "author": { + "name": "18816895620", + "image_url": "avatars/User/b" + }, + "category": { + "id": 1, + "name": "大数据" + }, + "language": { + "id": 2, + "name": "C" + } }, - "language": { - "id": 2, - "name": "C" - } - }, - { - "id": "mirror_demo", - "name": "ni项目", - "description": "my first project", - "visits": 0, - "forked_count": 0, - "is_public": false, - "mirror_url": "https://gitea.com/CasperVector/slew.git", - "last_update_time": 1577085412, - "author": { - "name": "18816895620" + { + "id": "tongjj", + "name": "统计局", + "description": "my first project", + "visits": 0, + "praises_count": 0, + "forked_count": 0, + "is_public": true, + "mirror_url": null, + "last_update_time": 1577415173, + "author": { + "name": "18816895620", + "image_url": "avatars/User/b" + }, + "category": { + "id": 1, + "name": "大数据" + }, + "language": { + "id": 2, + "name": "C" + } }, - "category": { - "id": 1, - "name": "大数据" + { + "id": null, + "name": "开源同名", + "description": "my first project", + "visits": 0, + "praises_count": 0, + "forked_count": 0, + "is_public": false, + "mirror_url": "https://gitea.com/CasperVector/slew.git", + "last_update_time": 1577346228, + "author": { + "name": "18816895620", + "image_url": "avatars/User/b" + }, + "category": { + "id": 1, + "name": "大数据" + }, + "language": { + "id": 2, + "name": "C" + } }, - "language": { - "id": 2, - "name": "C" + { + "id": "mvp_demo", + "name": "开源支持", + "description": "my first project", + "visits": 0, + "praises_count": 0, + "forked_count": 0, + "is_public": true, + "mirror_url": null, + "last_update_time": 1577341572, + "author": { + "name": "18816895620", + "image_url": "avatars/User/b" + }, + "category": { + "id": 1, + "name": "大数据" + }, + "language": { + "id": 2, + "name": "C" + } } - } -] + ] +} ``` --- @@ -633,22 +747,125 @@ curl -X GET http://localhost:3000/api/projects/mirror_demo/branches | jq |参数名|类型|说明| -|-|- -|name |string|分支名称| +|name |string|分支名称| +|user_can_push |boolean|用户是否可push| +|user_can_merge |boolean|用户是否客merge| +|protected |boolean|是否为保护分支| +|last_commit |object|最后提交记录| +|-- id |string|提交记录id| +|-- message |string|提交的说明信息| +|-- timestamp |int|提交时间，为UNIX时间戳| +|-- time_from_now|string|转换后的时间| +|author |object|提交用户| +|-- login |string|用户名称| +|-- image_url |string|用户头像| 返回值 ``` [ { - "name": "develop" + "name": "develop", + "user_can_push": true, + "user_can_merge": true, + "protected": false, + "last_commit": { + "id": "735674d6696bddbafa993db9c67b40c41246c77f", + "message": "FIX test branch content\n", + "timestamp": 1577694074, + "time_from_now": "1天前" + }, + "author": { + "login": "18816895620", + "image_url": "avatars/User/b" + } }, { - "name": "master" + "name": "master", + "user_can_push": true, + "user_can_merge": true, + "protected": false, + "last_commit": { + "id": "19ac3bc45f62cc87a94b8ecce61101d8fd2dafd2", + "message": "合并pull request测试\n\n该功能很不错，感谢你的建议\n", + "timestamp": 1577244567, + "time_from_now": "6天前" + }, + "author": { + "login": "18816895620", + "image_url": "avatars/User/b" + } } ] ``` --- +## 获取提交记录列表 +``` +GET /api/:login/:repo_identifier/commits +``` +*示例* +``` +curl -X GET \ +-d "sha=develop" \ +-d "page=1" \ +http://localhost:3000/api/18816895620/mirror_demo/commits | jq +``` +*请求参数说明:* + +|参数名|必选|类型|说明| +-|-|-|- +|login |是|string |用户标识 | +|repo_identifier |是|string |仓库标识 | +|sha |否|string |分支名称、提交记录的sha标识，默认为master分支 | +|page |否|int |页数， 默认为1 | + + +*返回参数说明:* + +|参数名|类型|说明| +-|-|- +|total_count|int|总记录条数| +|commits |array|提交记录的数组| +|-- sha |string|提交记录sha标识| +|-- message |string|提交的备注说明| +|-- timestamp |int|提交UNIX时间戳| +|-- time_from_now|string|提交距离当前的时间| +|author |object|提交用户| +|-- login |string|用户名称| +|-- image_url |string|用户头像| + + +返回值 +``` +{ + "total_count": 63, + "commits": [ + { + "sha": "19ac3bc45f62cc87a94b8ecce61101d8fd2dafd2", + "message": "合并pull request测试", + "timestamp": 1577244567, + "time_from_now": "7天前", + "author": { + "name": "18816895620", + "image_url": "avatars/User/b" + } + }, + { + "sha": "2b33c5f55214db41879936312ee43611406c4dbd", + "message": "FIX .", + "timestamp": 1577244474, + "time_from_now": "7天前", + "author": { + "name": "18816895620", + "image_url": "avatars/User/b" + } + } + ] +} +``` +--- + ### 点赞 ``` POST /api/praise_tread/like