[add]docs &
This commit is contained in:
parent
aac247698e
commit
e71bbf3eb5
@ -1,5 +1,3 @@
|
||||
# RESTFul API 文档 v1.0
|
||||
|
||||
## 1. 用户注册
|
||||
|
||||
### 1.1 接口描述
|
||||
@ -35,18 +33,18 @@ Content-Type: application/json
|
||||
```
|
||||
|
||||
### 1.7 返回参数说明
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|
||||
|-----------| ---- | -------- | -------- | ---------------------------- |
|
||||
| code | 是 | 整型 | | 错误码，200表示成功 |
|
||||
| message | 否 | 字符串 | 1-50字符 | 错误信息描述 |
|
||||
| data | 否 | json | | 具体业务数据 |
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|
||||
|------| ---- | -------- | -- |-----------|
|
||||
| code | 是 | 整型 | | 错误码，0表示成功 |
|
||||
| msg | 否 | 字符串 | | 错误信息描述 |
|
||||
| data | 否 | json | | 具体业务数据 |
|
||||
|
||||
data结构说明：
|
||||
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|
||||
|-----------| ---- | -------- | -------- | ---------------------------- |
|
||||
| id | 是 | 整型 | | 用户id |
|
||||
| username | 是 | 字符串 | 1-50字符 | 登录账号|
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|
||||
|-----------| ---- | -------- |--------| ---------------------------- |
|
||||
| id | 是 | 整型 | | 用户id |
|
||||
| username | 是 | 字符串 | 1-32字符 | 登录账号|
|
||||
|
||||
|
||||
|
||||
@ -57,7 +55,7 @@ data结构说明：
|
||||
```
|
||||
### 1.9 响应示例（错误）
|
||||
```json
|
||||
{ "code": 10001, "msg": "验证码无效" }
|
||||
{ "code": 409, "msg": "用户名存在" }
|
||||
```
|
||||
|
||||
### 1.10 错误响应码参考
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
# RESTFul API 文档 v1.0
|
||||
|
||||
## 1. 用户登录接口
|
||||
|
||||
### 1.1 接口描述
|
||||
@ -16,10 +14,10 @@
|
||||
| Content-Type | 是 | application/json | 指定请求体的媒体类型为JSON |
|
||||
|
||||
### 1.5 请求体参数
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 |
|
||||
|-----------| ---- | -------- | -------- | ---------------------------- | ------------ | -------- |
|
||||
| username | 是 | 字符串 | 1-50字符 | 用于登录的账号（手机号或邮箱） | "user123" | 否 |
|
||||
| password | 是 | 字符串 | 1-50字符 | 密码 | "p@ssw0rd" | 否 |
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 |
|
||||
|-----------| ---- | -------- |--------| ---------------------------- | ------------ | -------- |
|
||||
| username | 是 | 字符串 | 1-32字符 | 用于登录的账号（手机号或邮箱） | "user123" | 否 |
|
||||
| password | 是 | 字符串 | 1-32字符 | 密码 | "p@ssw0rd" | 否 |
|
||||
|
||||
|
||||
### 1.6 请求示例
|
||||
@ -35,11 +33,11 @@ Content-Type: application/json
|
||||
```
|
||||
|
||||
### 1.7 返回参数说明
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|
||||
|-----------| ---- | -------- | -------- | ---------------------------- |
|
||||
| code | 是 | 整型 | | 错误码，200表示成功 |
|
||||
| message | 否 | 字符串 | 1-50字符 | 错误信息描述 |
|
||||
| data | 否 | json | | 具体业务数据 |
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|
||||
|------| ---- | -------- | -- |-----------|
|
||||
| code | 是 | 整型 | | 错误码，0表示成功 |
|
||||
| msg | 否 | 字符串 | | 错误信息描述 |
|
||||
| data | 否 | json | | 具体业务数据 |
|
||||
|
||||
|
||||
data结构说明：
|
||||
@ -55,7 +53,7 @@ data结构说明：
|
||||
```
|
||||
### 1.9 响应示例（错误）
|
||||
```json
|
||||
{ "code": 10001, "msg": "验证失败" }
|
||||
{ "code": 401, "msg": "验证失败" }
|
||||
```
|
||||
|
||||
### 1.10 错误响应码参考
|
||||
|
||||
94
docs/api doc/获取用户个人信息接口.md
Normal file
94
docs/api doc/获取用户个人信息接口.md
Normal file
@ -0,0 +1,94 @@
|
||||
## 1. 获取用户个人信息接口
|
||||
|
||||
### 1.1 接口描述
|
||||
获取当前登录用户的个人信息。
|
||||
### 1.2 请求URL
|
||||
`/v1/user/info`
|
||||
|
||||
### 1.3 请求方式
|
||||
**GET**
|
||||
|
||||
### 1.4 请求头
|
||||
| 头字段 | 必填 | 数据类型 | 描述 |
|
||||
| ------------ | ---- | ------------- | -------------------------------- |
|
||||
|
||||
|
||||
### 1.5 请求体参数
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 |
|
||||
|-----------| ---- | -------- | -------- | ---------------------------- | ------------ | -------- |
|
||||
|
||||
|
||||
### 1.6 请求示例
|
||||
```http
|
||||
GET /api/user/signup
|
||||
```
|
||||
|
||||
### 1.7 返回参数说明
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|
||||
|------| ---- | -------- | -- |-----------|
|
||||
| code | 是 | 整型 | | 错误码，0表示成功 |
|
||||
| msg | 否 | 字符串 | | 错误信息描述 |
|
||||
| data | 否 | json | | 具体业务数据 |
|
||||
|
||||
data结构说明：
|
||||
|
||||
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|
||||
|----------| --- | -------- |--|------|
|
||||
| id | 是 | 整型 | | 用户id |
|
||||
| username | 是 | 字符串 | 1-32字符 | 登录账号 |
|
||||
| ... | | | | |
|
||||
| follows | 是 | 整型 | | 关注我的 |
|
||||
| followings | 是 | 整型 | | 我关注的 |
|
||||
| tweets_count | 是 | 整型 | | |
|
||||
|
||||
|
||||
### 1.8 响应示例（成功）
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": 100066,
|
||||
"nickname": "xyz",
|
||||
"username": "xyz",
|
||||
"status": 1,
|
||||
"avatar": "https://assets.paopao.info/public/avatar/default/jackson.png",
|
||||
"phone": "",
|
||||
"is_admin": false,
|
||||
"created_on": 1714290963,
|
||||
"follows": 0,
|
||||
"followings": 0,
|
||||
"tweets_count": 4
|
||||
}
|
||||
}
|
||||
```
|
||||
### 1.9 响应示例（错误）
|
||||
```json
|
||||
{ "code": 500, "msg": "内部错误" }
|
||||
```
|
||||
|
||||
### 1.10 错误响应码参考
|
||||
更多响应错误码及含义，请参阅[API响应码表](URL/for/api/responseCode/table)。
|
||||
|
||||
### 1.11 安全性与认证
|
||||
|
||||
|
||||
### 1.12 测试环境
|
||||
访问测试环境以进行接口调试：
|
||||
[https://test.apiAddress.com](https://test.apiAddress.com)
|
||||
|
||||
### 1.13 版本管理
|
||||
本API通过URI路径进行版本控制。请在请求URL中包含`/v1`以使用当前版本。
|
||||
|
||||
### 1.14 更新记录
|
||||
- **2024-05-07**：添加data结构说明
|
||||
- **2024-04-29**：发布文档初始版本。
|
||||
|
||||
|
||||
### 1.15 联系支持
|
||||
如需帮助或对API有任何疑问，请通过电子邮件与我们联系：[support@api.com](mailto:support@api.com)。
|
||||
|
||||
### 1.16 反馈与建议
|
||||
发现文档问题或有改进建议？请填写[反馈表单](https://forms.api.com/feedback)与我们分享。
|
||||
|
||||
32
docs/guides/git工作流.md
Normal file
32
docs/guides/git工作流.md
Normal file
@ -0,0 +1,32 @@
|
||||
### 单一`master`分支的Git工作流:
|
||||
|
||||
1. **仓库初始化**：
|
||||
- 在GitHub、GitLab或其他代码托管平台上创建一个新的仓库。
|
||||
- 在本地机器上，使用`git clone`命令克隆远程仓库到本地。
|
||||
|
||||
2. **工作开始**：
|
||||
- 进入项目目录，使用`cd`命令。
|
||||
- 确保始终处于`master`分支，可通过`git branch`查看当前分支，或使用`git checkout master`切换到`master`分支。
|
||||
|
||||
3. **日常开发**：
|
||||
- 在`master`分支上直接进行文件的修改、新增或删除。
|
||||
- 使用`git status`查看工作区的状态，了解哪些文件已被修改或新增。
|
||||
- 使用`git add .`或`git add <file>`将改动的文件添加到暂存区。
|
||||
- 使用`git commit -m "commit message"`提交改动到本地仓库，记得附上清晰的提交信息。
|
||||
|
||||
4. **推送到远程仓库**：
|
||||
- 使用`git push origin master`将本地`master`分支的改动推送到远程仓库的`master`分支。
|
||||
- 如果是首次推送，可能需要添加`-u`参数来建立跟踪关系，如`git push -u origin master`。
|
||||
|
||||
5. **协作与冲突解决**：
|
||||
- 在多人协作时，确保及时拉取远程的最新改动到本地，使用`git pull origin master`。
|
||||
- 如果出现冲突，Git会提示冲突文件，需要手动编辑这些文件解决冲突，保留或合并必要的改动。
|
||||
- 解决冲突后，再次使用`git add`和`git commit`提交解决冲突后的版本，并推送。
|
||||
|
||||
6. **代码审查与反馈**：
|
||||
- 即使在简化的工作流中，也应该鼓励团队成员相互查看提交的代码，可以通过Pull Request（即使是在同一个分支内）或代码审查工具来进行。
|
||||
|
||||
7. **版本标记**：
|
||||
- 对于重要的里程碑或发布版本，可以使用`git tag`命令打标签，例如`git tag v1.0.0`，然后使用`git push origin --tags`将标签推送到远程仓库。
|
||||
|
||||
尽管此流程简单，但重要的是要意识到，随着项目复杂度和团队规模的增长，这种单一`master`分支的模式很容易导致混乱和错误。推荐过渡到更成熟的工作流，比如引入`develop`分支作为日常开发分支，以及使用功能分支进行特性开发和隔离，最终通过 Pull Request 合并到主分支，以保持代码质量和团队协作效率。
|
||||
@ -148,6 +148,47 @@ springdoc:
|
||||
</configuration>
|
||||
|
||||
```
|
||||
|
||||
- **JSON配置项**
|
||||
|
||||
在`application.yml`中添加配置,设置JSON的属性命名策略为SNAKE_CASE：
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
jackson:
|
||||
property-naming-strategy: SNAKE_CASE # 驼峰转下划线
|
||||
```
|
||||
|
||||
在Spring Boot应用中，可以通过`spring.jackson`命名空间下的配置项来定制Jackson库的行为，以适应不同的JSON序列化和反序列化需求。以下是一些关键的配置项示例及其功能：
|
||||
|
||||
> **默认属性包含策略**:
|
||||
- `spring.jackson.default-property-inclusion`: 控制哪些属性会被序列化到JSON中，可选值包括`ALWAYS`, `NON_NULL`, `NON_EMPTY`, `USE_DEFAULTS`, `NON_ABSENT`, 和 `CUSTOM`。例如，设置为`NON_NULL`可避免null值的字段出现在JSON输出中。
|
||||
> **日期格式化**:
|
||||
- `spring.jackson.date-format`: 允许配置日期格式字符串，或者指定一个日期格式化类的全限定名，如使用`java.text.SimpleDateFormat`的格式。
|
||||
- `spring.jackson.time-zone`: 设置日期时间序列化和反序列化时使用的时区。
|
||||
|
||||
> **缩进和美化输出**:
|
||||
- `spring.jackson.serialization.indent-output`: 布尔值，决定是否在输出的JSON中加入缩进以美化格式，默认为`false`。
|
||||
|
||||
> **时间戳格式**:
|
||||
- `spring.jackson.serialization.write-dates-as-timestamps`: 决定日期是否应该被序列化为时间戳（毫秒数）而不是字符串格式，默认为`true`。
|
||||
|
||||
> **未知属性处理**:
|
||||
- `spring.jackson.deserialization.fail-on-unknown-properties`: 当JSON中包含Java对象模型中不存在的属性时，决定是否抛出异常，默认为`false`意味着忽略未知属性。
|
||||
|
||||
> **属性命名策略**:
|
||||
- `spring.jackson.property-naming-strategy`: 可以设置属性命名策略，如`LOWER_CAMEL_CASE`, `UPPER_CAMEL_CASE`, `KEBAB_CASE`, `SNAKE_CASE`, 或自定义实现的全限定名。
|
||||
|
||||
> **特性包含与忽略**:
|
||||
- 可以通过特定的配置来控制Jackson的特性，比如`spring.jackson.features.*`，这里`*`代表Jackson中的特性标识，例如`FAIL_ON_UNKNOWN_PROPERTIES`等。
|
||||
|
||||
> **自定义ObjectMapper**:
|
||||
- 如果上述配置不能满足需求，可以通过定义一个`ObjectMapper` Bean来实现更复杂的自定义配置。
|
||||
|
||||
请注意，实际可用的配置项可能依据Spring Boot的版本不同而有所差异，建议查阅对应版本的官方文档以获取最新和最准确的配置信息。
|
||||
|
||||
|
||||
|
||||
#### 6、配置h2数据库和JPA
|
||||
|
||||
项目使用h2数据库作为默认的数据库，并使用JPA作为ORM框架。
|
||||
|
||||
@ -27,10 +27,11 @@ public class UserDto implements Serializable {
|
||||
String phone;
|
||||
Byte status;
|
||||
String avatar;
|
||||
Long balance;
|
||||
Boolean isAdmin;
|
||||
Integer follows=0;
|
||||
Integer followings=0;
|
||||
Integer tweetsCount=0;
|
||||
}
|
||||
|
||||
```
|
||||
> @Value 是 Lombok 库提供的一个注解，用于简化 Java 类的编写。当这个注解应用在一个类上时，Lombok 会自动为类的所有字段生成以下内容：
|
||||
- 私有字段（Private fields）：所有字段默认变为私有，并且没有公共访问器（getter 和 setter）。
|
||||
|
||||
@ -16,6 +16,8 @@ public class UserDto implements Serializable {
|
||||
String phone;
|
||||
Byte status;
|
||||
String avatar;
|
||||
Long balance;
|
||||
Boolean isAdmin;
|
||||
Integer follows=0;
|
||||
Integer followings=0;
|
||||
Integer tweetsCount=0;
|
||||
}
|
||||
@ -3,6 +3,10 @@ springdoc:
|
||||
path: /api-docs
|
||||
|
||||
spring:
|
||||
|
||||
jackson:
|
||||
property-naming-strategy: SNAKE_CASE # 驼峰转下划线
|
||||
|
||||
datasource:
|
||||
url: jdbc:h2:file:./paopao.h2 # 使用文件存储
|
||||
driverClassName: org.h2.Driver
|
||||
@ -45,4 +49,4 @@ app:
|
||||
- path: "/v1/auth/**"
|
||||
methods: [ "GET","PUT","POST"]
|
||||
allowed-origins:
|
||||
- "http://localhost:8080"
|
||||
- "http://localhost:5173"
|
||||
Loading…
Reference in New Issue
Block a user