api文档 中文版

API 文档

一、

本 API 提供了一系列功能，用于实现[具体业务目标]，它允许用户通过 HTTP 请求与系统进行交互，获取或提交数据。

二、基础信息

参数	说明
请求方式	支持 GET、POST、PUT、DELETE 等常见 HTTP 方法。
请求路径	以“/api/”为基本路径，后接具体功能模块及操作路径。
响应格式	默认返回 JSON 格式数据，包含状态码、消息及数据内容。

三、功能模块

（一）用户管理

1、注册

请求 URL：/api/user/register

请求方式：POST

请求参数：

	参数名	类型	必填	描述
	username	string	是	用户名，长度 3 16 位，仅支持字母数字组合。
	password	string	是	密码，长度 8 20 位，需包含大小写字母、数字和特殊字符。
	email	string	是	有效的邮箱地址。

响应示例：

        {
            "code": 200,
            "message": "注册成功",
            "data": {
                "userId": 12345
            }
        }

2、登录

请求 URL：/api/user/login

请求方式：POST

请求参数：

	参数名	类型	必填	描述
	username	string	是	用户名。
	password	string	是	密码。

响应示例：

        {
            "code": 200,
            "message": "登录成功",
            "data": {
                "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
            }
        }

3、获取用户信息

请求 URL：/api/user/info

请求方式：GET

请求参数：无（需携带有效 token）。

响应示例：

        {
            "code": 200,
            "message": "查询成功",
            "data": {
                "userId": 12345,
                "username": "testUser",
                "email": "test@example.com"
            }
        }

（二）文章管理

1、发布文章

请求 URL：/api/article/publish

请求方式：POST

请求参数：

	参数名	类型	必填	描述
	title	string	是	文章标题，长度不超过 50 字。
	content	string	是	文章内容，支持富文本格式。
	categoryId	int	是	文章分类 ID。

响应示例：

        {
            "code": 200,
            "message": "文章发布成功",
            "data": {
                "articleId": 67890
            }
        }

2、获取文章列表

请求 URL：/api/article/list

请求方式：GET

请求参数：

	参数名	类型	必填	描述
	pageNum	int	否	页码，默认为 1。
	pageSize	int	否	每页显示数量，默认为 10。
	categoryId	int	否	文章分类 ID，不传则查询所有分类文章。

响应示例：

        {
            "code": 200,
            "message": "查询成功",
            "data": [
                {
                    "articleId": 67890,
                    "title": "测试文章标题",
                    "categoryName": "技术",
                    "createTime": "2024-10-10T10:00:00Z"
                },
                ...
            ],
            "total": 100
        }

3、获取文章详情

请求 URL：/api/article/detail/{articleId}

请求方式：GET

请求参数：无（articleId为路径参数）。

响应示例：

        {
            "code": 200,
            "message": "查询成功",
            "data": {
                "articleId": 67890,
                "title": "测试文章标题",
                "content": "<p>这里是文章内容</p>",
                "categoryId": 1,
                "categoryName": "技术",
                "createTime": "2024-10-10T10:00:00Z",
                "updateTime": "2024-10-11T12:00:00Z"
            }
        }

四、相关问题与解答

（一）问题一：注册时用户名已存在如何处理？

答：如果注册时用户名已存在，API 会返回相应的错误提示，如：

{
    "code": 400,
    "message": "用户名已存在"
}

建议前端在收到此错误后，及时向用户反馈，提示其更换用户名。

（二）问题二：文章发布时缺少必要字段会怎样？

答：当发布文章时，如果缺少必填字段，API 会返回错误信息，例如缺少标题时：

{
    "code": 400,
    "message": "标题不能为空"
}

前端应检查返回的错误码和消息，并引导用户提供完整的信息后再尝试发布。

小伙伴们，上文介绍了“api文档 中文版”的内容，你了解清楚吗？希望对你有所帮助，任何问题可以给我留言，让我们下期再见吧。