1. 概览

RESTful API | bookshelf.plus

1.1. 版本信息

版本 : 1.0

1.2. URI scheme

域名 : localhost:8090

1.3. 标签

  • 书籍信息 : Book Controller

  • 书籍分类信息 : Category Controller

  • 用户操作 : User Controller

  • 第三方登录 : Third Party Controller

  • 系统调试接口 : Debug Controller

  • 网站后台状态检测 : Status Controller

2. 资源

2.1. 书籍信息

Book Controller

2.1.1. 【管理员】删除书籍

POST /api/book/delete
说明

管理员在后台删除书籍

参数
类型 名称 类型

FormData

id
可选

integer (int32)

FormData

token
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/book/delete
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.1.2. 【管理员】添加/修改书籍

POST /api/book/detail
说明

管理员在后台添加/修改书籍（bookId 传 0 或 null 或 不传 即为添加）

参数
类型 名称 类型

FormData

author
可选

string

FormData

bookName
可选

string

FormData

categoryId
可选

integer (int32)

FormData

copyright
可选

string

FormData

description
可选

string

FormData

id
可选

integer (int32)

FormData

isDelete
可选

boolean

FormData

language
可选

string

FormData

publishingHouse
可选

string

FormData

thumbnail
可选

string

FormData

token
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/book/detail
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.1.3. 获取书籍信息

GET /api/book/get
说明

获取书籍信息

参数
类型 名称 说明 类型

Query

id
必填

id

integer (int32)
响应
HTTP代码 说明 类型

200

OK

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
生成

  • */*

HTTP请求示例
请求 path
/api/book/get?id=0
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.1.4. 【用户】收藏/取消收藏书籍

POST /api/book/getFavoritesStatus
说明

用户收藏书籍

参数
类型 名称 类型

FormData

bookId
可选

integer (int32)

FormData

token
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/book/getFavoritesStatus
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.1.5. 查询书籍列表

GET /api/book/search
说明

通过指定条件查询书籍列表

参数
类型 名称 说明 类型

Query

author
可选

author

string

Query

bookName
可选

bookName

string

Query

categoryId
可选

categoryId

integer (int32)

Query

id
可选

id

integer (int32)

Query

language
可选

language

string

Query

publishingHouse
可选

publishingHouse

string
响应
HTTP代码 说明 类型

200

OK

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
生成

  • */*

HTTP请求示例
请求 path
/api/book/search
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.1.6. 【用户】收藏/取消收藏书籍

POST /api/book/toggleFavorites
说明

用户收藏书籍

参数
类型 名称 类型

FormData

bookId
可选

integer (int32)

FormData

status
可选

boolean

FormData

token
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/book/toggleFavorites
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.2. 书籍分类信息

Category Controller

2.2.1. 获取指定分类

GET /api/category/get
说明

获取指定的书籍分类

参数
类型 名称 说明 类型

Query

id
必填

id

integer (int32)
响应
HTTP代码 说明 类型

200

OK

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
生成

  • */*

HTTP请求示例
请求 path
/api/category/get?id=0
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.2.2. 获取所有分类

GET /api/category/list
说明

获取所有的书籍分类

响应
HTTP代码 说明 类型

200

OK

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
生成

  • */*

HTTP请求示例
请求 path
/api/category/list
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.3. 用户操作

User Controller

2.3.1. 账号注销

POST /api/user/cancelAccount
说明

传入用户 token ，以及密码明文，后台计算密码SHA1值，进行注销

参数
类型 名称 类型

FormData

password
可选

string

FormData

token
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/user/cancelAccount
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.3.2. 获取用户登录状态

POST /api/user/getUserStatus
说明

获取用户登录状态

参数
类型 名称 类型

FormData

token
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/user/getUserStatus
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.3.3. 用户登录

POST /api/user/login
说明

传入用户名，以及密码明文，后台计算密码SHA1值，进行登录

参数
类型 名称 类型

FormData

password
可选

string

FormData

username
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/user/login
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.3.4. 用户登出

POST /api/user/logout
说明

用户退出登录

参数
类型 名称 类型

FormData

token
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/user/logout
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.3.5. 用户注册

POST /api/user/register
说明

传入用户名，以及密码明文，后台计算密码SHA1值，进行注册

参数
类型 名称 类型

FormData

password
可选

string

FormData

username
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/user/register
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.4. 第三方登录

Third Party Controller

2.4.1. 快捷登录回调函数

GET /api/third-party/callback/{platform}
说明

如果传入 token 那么就是绑定第三方账号到当前登录账号，否则就是通过第三方授权登录

参数
类型 名称 说明 类型

Path

platform
必填

platform

string

Query

auth_code
可选

string

Query

authorization_code
可选

string

Query

code
可选

string

Query

oauth_token
可选

string

Query

oauth_verifier
可选

string

Query

state
可选

string

Query

token
可选

token

string
响应
HTTP代码 说明 类型

200

OK

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
生成

  • */*

HTTP请求示例
请求 path
/api/third-party/callback/string
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.4.2. 获取用户已绑定的第三方平台

GET /api/third-party/getBindingStatus
说明

传入当前登录用户 token ，返回已绑定的第三方平台

参数
类型 名称 说明 类型

Query

token
可选

token

string
响应
HTTP代码 说明 类型

200

OK

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
生成

  • */*

HTTP请求示例
请求 path
/api/third-party/getBindingStatus
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.4.3. 第三方用户登录跳转地址

GET /api/third-party/login
说明

传入需要登录的第三方平台（大小写均可），返回跳转url

参数
类型 名称 说明 类型

Query

platform
必填

platform

string
响应
HTTP代码 说明 类型

200

OK

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
生成

  • */*

HTTP请求示例
请求 path
/api/third-party/login?platform=string
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.4.4. 取消第三方平台绑定

POST /api/third-party/withdrawThirdPartyBings
说明

传入当前登录用户 token 和平台 platform （不区分大小写），返回 bool 值，true 为取消绑定成功

参数
类型 名称 类型

FormData

platform
可选

string

FormData

token
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/third-party/withdrawThirdPartyBings
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.5. 系统调试接口

Debug Controller

2.5.1. 获取系统配置

POST /api/debug/status
说明

仅限管理员登录状态下可获取

参数
类型 名称 类型

FormData

token
可选

string
响应
HTTP代码 说明 类型

200

OK

201

Created

无内容

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
消耗

  • application/x-www-form-urlencoded

生成

  • */*

HTTP请求示例
请求 path
/api/debug/status
请求 formData
"string"
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

2.6. 网站后台状态检测

Status Controller

2.6.1. 系统状态

GET /api/status/get
说明

获取服务器当前系统负载。SystemLoadAverage返回-1时代表不支持。

响应
HTTP代码 说明 类型

200

OK

401

Unauthorized

无内容

403

Forbidden

无内容

404

Not Found

无内容
生成

  • */*

HTTP请求示例
请求 path
/api/status/get
HTTP响应示例
响应 200
{
  "data" : "object",
  "status" : "string"
}

3. 定义

3.1. CommonReturnType

名称 说明 类型

data
可选

样例 : "object"

object

status
可选

样例 : "string"

string