Update the usage documentation

docs/clients/dingding.md

@@ -0,0 +1,5 @@
+## 创建第三方应用
+
+登录登录钉钉开发者后台：[open-dev.dingtalk](https://open-dev.dingtalk.com/)
+
+...

docs/clients/douyin.md

@@ -0,0 +1,5 @@
+## 创建第三方应用
+
+访问抖音开放平台：[open.douyin](https://open.douyin.com/)
+
+...

docs/clients/feishu.md

@@ -0,0 +1,9 @@
+## 注册账号
+
+地址：[gitee](https://gitee.com/)
+
+如果已有则忽略该步骤，直接进入第二步
+
+## 创建第三方应用
+
+登录已注册的账号...

docs/clients/gitee.md

@@ -0,0 +1,9 @@
+## 注册账号
+
+地址：[gitee](https://gitee.com/)
+
+如果已有则忽略该步骤，直接进入第二步
+
+## 创建第三方应用
+
+登录已注册的账号...

docs/clients/github.md

@@ -0,0 +1,42 @@
+## 注册账号
+
+地址：[GitHub](https://github.com/)
+
+如果已有则忽略该步骤，直接进入第二步
+
+## 创建第三方应用
+
+### 登录
+
+登录已注册的账号，通过主页右上角进入个人设置页：[profile](https://github.com/settings/profile)
+
+![settings.png](../public/images/github/settings.png)
+
+### 创建应用
+
+进入开发者界面：[Developer settings](https://github.com/settings/apps)
+
+![dev.png](../public/images/github/dev.png)
+
+创建 OAuth app：[OAuth apps](https://github.com/settings/developers)
+
+![oauth.png](../public/images/github/oauth.png)
+
+- `Application name` 填写自己的网站名称
+- `Homepage URL` 填写自己的网站首页地址
+- `Application description` 填写自己的应用描述
+- `Authorization callback URL` 用户授权后跳转到自己平台的地址。通常情况下，开发者需要在此路由代码中实现自己平台用户的注册、绑定等操作
+- `Enable Device Flow` 不需要勾选
+
+信息输入完成后，点击下方绿色的 ==`Register applaction`== 按钮创建应用
+
+![register.png](../public/images/github/register.png)
+
+### 创建密钥
+
+创建完成后，进入应用详情页，`Client secrets`
+
+![secrets.png](../public/images/github/secrets.png)
+
+创建完成后，记录 `Client ID`、`Client Secret`、`Authorization callback URL`，这三个东西在我们集成的时候都用得到，请妥善保管
+ID 和 Secret

docs/clients/google.md

@@ -0,0 +1,5 @@
+## 创建第三方应用
+
+登录 Google 开发者中心：[console.developers.google](https://console.developers.google.com/apis/dashboard)
+
+...

docs/clients/linuxdo.md

@@ -0,0 +1,33 @@
+## 注册账号
+
+地址：[LinuxDo](https://linux.do/)
+
+如果已有则忽略该步骤，直接进入第二步
+
+## 创建第三方应用
+
+### 登录
+
+登录已注册的账号，通过主页左侧 Connect 进入 connect 页面：[connect](https://connect.linux.do/)
+
+![connect.png](../public/images/linuxdo/connect.png)
+
+### 创建应用
+
+进入开发者界面：[sso](https://connect.linux.do/dash/sso)
+
+![dev.png](../public/images/linuxdo/dev.png)
+
+申请新接入：[new](https://connect.linux.do/dash/sso/new)
+
+![new.png](../public/images/linuxdo/new.png)
+
+信息输入完成后，点击下方蓝色的 ==`保存`== 按钮创建应用
+
+![save.png](../public/images/linuxdo/save.png)
+
+创建完成后，进入应用详情页
+
+![secrets.png](../public/images/linuxdo/secrets.png)
+
+记录 `Client ID`、`Client Secret`、`回调地址`，这三个东西在我们集成的时候都用得到，请妥善保管 ID 和 Secret

docs/clients/oschina.md

@@ -0,0 +1,9 @@
+## 注册账号
+
+地址：[oschina](https://www.oschina.net/)
+
+如果已有则忽略该步骤，直接进入第二步
+
+## 创建第三方应用
+
+登录已注册的账号...

docs/clients/qq.md

@@ -0,0 +1,5 @@
+## 创建第三方应用
+
+登录QQ互联平台：[QQ](https://connect.qq.com/)
+
+...

docs/clients/wechat_mp.md

@@ -0,0 +1,5 @@
+## 创建第三方应用
+
+登录微信小程序控制台：[mp.weixin](https://mp.weixin.qq.com/)
+
+...

docs/clients/wechat_open.md

@@ -0,0 +1,9 @@
+## 注册账号
+
+地址：[open.weixin](https://open.weixin.qq.com/)
+
+如果已有则忽略该步骤，直接进入第二步
+
+## 创建第三方应用
+
+登录已注册的账号...

docs/clients/wechat_work.md

@@ -0,0 +1,5 @@
+## 创建第三方应用
+
+登录微信企业版控制台：[work.weixin](https://work.weixin.qq.com/wework_admin/loginpage_wx?from=myhome_openApi)
+
+...

docs/clients/weibo.md

@@ -0,0 +1,9 @@
+## 注册账号
+
+地址：[weibo](https://open.weibo.com/apps)
+
+如果已有则忽略该步骤，直接进入第二步
+
+## 创建第三方应用
+
+登录已注册的账号...

docs/explanation.md

@@ -1 +1,25 @@
-TODO...
+!!! note
+
+    - `开发者` 指使用JustAuth的开发者
+    - `第三方` 指开发者对接的第三方客户端，比如：Google、GitHub、Gitee 等
+    - `用户` 指最终服务的真实用户
+
+- ==client_id== 客户端身份标识符（应用id），一般在申请完 `OAuth` 应用后，由第三方客户端颁发
+- ==client_secret== 客户端密钥，一般在申请完 `OAuth` 应用后，由第三方客户端颁发
+- ==redirect_uri== 开发者项目中真实有效的 API 地址。用户在确认第三方客户端授权（登录）后，第三方客户端会自动重定向到该地址，并携带
+  code 等参数
+- ==state== 用于在请求和回调之间维护状态，主要用于防止跨站请求伪造（CSRF）攻击
+- ==source== 支持的第三方客户端，比如：GitHub、LinuxDo 等
+- ==sid== 第三方客户端的用户 ID。以下是关于各平台的 sid 存储逻辑：
+
+!!! warning
+
+    建议通过 `sid` + `source` 的方式确定唯一用户，这样可以解决用户身份归属的问题。因为 单个用户ID
+    在某一平台中是唯一的，但不能保证在所有平台中都是唯一的。
+
+## 参考资料
+
+关于 OAuth2 相关的内容、原理可以自行参阅以下资料：
+
+- [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
+- [OAuth 2.0](https://oauth.net/2/)

docs/fastapi.md

@@ -0,0 +1,46 @@
+提供的实用程序可简化 FastAPI 中 OAuth2 流程的集成
+
+## `FastAPIOAuth20`
+
+依赖关系可调用，用于处理授权回调，它读取查询参数并返回访问令牌和状态
+
+```python
+from fastapi import FastAPI, Depends
+from fastapi_oauth20 import FastAPIOAuth20, LinuxDoOAuth20
+
+client = LinuxDoOAuth20("CLIENT_ID", "CLIENT_SECRET")
+linuxdo_oauth2_callback = FastAPIOAuth20(client, "oauth2-callback")
+
+app = FastAPI()
+
+
+@app.get("/oauth2-callback", name="oauth-callback")
+async def oauth2_callback(access_token_state=Depends(linuxdo_oauth2_callback)):
+    token, state = access_token_state
+    # Do something useful
+```
+
+## 自定义异常
+
+如果回调逻辑内部发生错误（用户拒绝访问、授权代码无效......），依赖关系将引发 `OAuth20AuthorizeCallbackError` 错误
+
+它继承自 FastAPI 的 [HTTPException](https://fastapi.tiangolo.com/reference/exceptions/#fastapi.HTTPException)，因此默认的
+FastAPI 异常处理程序会自动对其进行处理。您可以通过为 `OAuth20AuthorizeCallbackError` 实现自己的异常处理程序来自定义此行为
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from fastapi_oauth20.integrations.fastapi import OAuth20AuthorizeCallbackError
+
+app = FastAPI()
+
+
+@app.exception_handler(OAuth20AuthorizeCallbackError)
+async def oauth2_authorize_callback_error_handler(request: Request, exc: OAuth20AuthorizeCallbackError):
+    detail = exc.detail
+    status_code = exc.status_code
+    return JSONResponse(
+        status_code=status_code,
+        content={"message": "The OAuth2 callback failed", "detail": detail},
+    )
+```

docs/index.md

@@ -16,7 +16,7 @@
 
 我们的目标是集成多个 CN 第三方客户端，敬请期待（🐦）...
 
-你可以在 [集成状态](integration.md) 获取当前集成情况
+你可以在 [客户端状态](status.md) 获取当前集成情况
 
 ## 互动
 

docs/install.md

@@ -7,20 +7,20 @@
 
 ## 安装
 
-=== ":simple-piped: pip"
+=== ":simple-python: pip"
 
     ```sh
     pip install fastapi-oauth20
     ```
 
-=== ":simple-pdm: pdm"
+=== ":simple-uv: uv"
 
     ```sh
-    pdm add fastapi-oauth20
+    uv add fastapi-oauth20
     ```
 
-=== ":simple-uv: uv"
+=== ":simple-pdm: pdm"
 
     ```sh
-    uv add fastapi-oauth20
+    pdm add fastapi-oauth20
     ```

docs/status.md

@@ -0,0 +1,24 @@
+下面展示了我们的计划，如果你有更多需求，请在仓库内创建 Issues，我们将尽力完成所有目标
+
+!!! danger
+
+    对于强制要求【实名 + 人脸认证】的平台，植入变得困难，所以它们不会很快到来
+
+## END
+
+- [x] [LinuxDo](clients/linuxdo.md)
+- [x] [GitHub](clients/github.md)
+- [x] [Gitee](clients/gitee.md)
+- [x] [开源中国](clients/oschina.md)
+- [x] [飞书](clients/feishu.md)
+- [x] [Google](clients/google.md)
+
+## TODO
+
+- [ ] [微信小程序](clients/wechat_open)
+- [ ] [微信开放平台](clients/wechat_mp)
+- [ ] [企业微信二维码登录](clients/wechat_work)
+- [ ] [钉钉](clients/dingding.md)
+- [ ] [QQ](clients/qq.md)
+- [ ] [微博](clients/weibo.md)
+- [ ] [抖音](clients/douyin.md)

mkdocs.yml

@@ -6,14 +6,29 @@ site_author: Wu Clan
 repo_name: fastapi-oauth20
 repo_url: https://github.com/wu-clan/fastapi-oauth20
 nav:
-  - Home:
-      - 主页: index.md
-      - 集成状态: integration.md
-  - Install: install.md
-  - Explanation: explanation.md
-  - Usage: usage.md
-  - Advanced: advanced.md
-  - Changelog: changelog.md
+  - 主页: index.md
+  - 安装: install.md
+  - 名词解释: explanation.md
+  - 用法: usage.md
+  - 高级用法: advanced.md
+  - 集成:
+      - FastAPI: fastapi.md
+  - 客户端状态: status.md
+  - 客户端申请:
+      - LinuxDo: clients/linuxdo.md
+      - GitHub: clients/github.md
+      - Gitee: clients/gitee.md
+      - 开源中国: clients/oschina.md
+      - 微信小程序: clients/wechat_open.md
+      - 微信开放平台: clients/wechat_mp.md
+      - 企业微信二维码登录: clients/wechat_work.md
+      - 飞书: clients/feishu.md
+      - 钉钉: clients/dingding.md
+      - QQ: clients/qq.md
+      - 微博: clients/weibo.md
+      - 抖音: clients/douyin.md
+      - Google: clients/google.md
+  - 变更日志: changelog.md
 theme:
   name: material
   font:
@@ -42,14 +57,14 @@ theme:
     - navigation.instant.progress
     - navigation.path
     - navigation.tracking
-    - navigation.tabs
     - navigation.tabs.sticky
     - navigation.top
     - navigation.footer
     - search.suggest
     - toc.follow
 plugins:
   - search
+  - glightbox
 markdown_extensions:
   - toc:
       permalink: true
@@ -58,9 +73,17 @@ markdown_extensions:
   - attr_list
   - def_list
   - md_in_html
-  - pymdownx.snippets
+  - admonition
+  - pymdownx.details
   - pymdownx.superfences
+  - pymdownx.snippets
   - pymdownx.inlinehilite
+  - pymdownx.critic
+  - pymdownx.caret
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.tilde
+  - pymdownx.blocks.caption
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span