Skip to content

Commit acb7877

Browse files
wu-clanwu-clan
authored
Update the usage documentation (#13)
* Update the usage documentation * update docs * update docs
1 parent cca1de1 commit acb7877

33 files changed

+305
-43
lines changed

‎docs/clients/dingding.md

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

‎docs/clients/douyin.md

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

‎docs/clients/feishu.md

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

‎docs/clients/gitee.md

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

‎docs/clients/github.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
## 注册账号
2+
3+
地址：[GitHub](https://github.com/)
4+
5+
如果已有则忽略该步骤，直接进入第二步
6+
7+
## 创建第三方应用
8+
9+
### 登录
10+
11+
登录已注册的账号，通过主页右上角进入个人设置页：[profile](https://github.com/settings/profile)
12+
13+
![settings.png](../public/images/github/settings.png)
14+
15+
### 创建应用
16+
17+
进入开发者界面：[Developer settings](https://github.com/settings/apps)
18+
19+
![dev.png](../public/images/github/dev.png)
20+
21+
创建 OAuth app：[OAuth apps](https://github.com/settings/developers)
22+
23+
![oauth.png](../public/images/github/oauth.png)
24+
25+
- `Application name` 填写自己的网站名称
26+
- `Homepage URL` 填写自己的网站首页地址
27+
- `Application description` 填写自己的应用描述
28+
- `Authorization callback URL` 用户授权后跳转到自己平台的地址。通常情况下，开发者需要在此路由代码中实现自己平台用户的注册、绑定等操作
29+
- `Enable Device Flow` 不需要勾选
30+
31+
信息输入完成后，点击下方绿色的 ==`Register applaction`== 按钮创建应用
32+
33+
![register.png](../public/images/github/register.png)
34+
35+
### 创建密钥
36+
37+
创建完成后，进入应用详情页，`Client secrets`
38+
39+
![secrets.png](../public/images/github/secrets.png)
40+
41+
创建完成后，记录 `Client ID`、`Client Secret`、`Authorization callback URL`，这三个东西在我们集成的时候都用得到，请妥善保管
42+
ID 和 Secret

‎docs/clients/google.md

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

‎docs/clients/linuxdo.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
## 注册账号
2+
3+
地址：[LinuxDo](https://linux.do/)
4+
5+
如果已有则忽略该步骤，直接进入第二步
6+
7+
## 创建第三方应用
8+
9+
### 登录
10+
11+
登录已注册的账号，通过主页左侧 Connect 进入 connect 页面：[connect](https://connect.linux.do/)
12+
13+
![connect.png](../public/images/linuxdo/connect.png)
14+
15+
### 创建应用
16+
17+
进入开发者界面：[sso](https://connect.linux.do/dash/sso)
18+
19+
![dev.png](../public/images/linuxdo/dev.png)
20+
21+
申请新接入：[new](https://connect.linux.do/dash/sso/new)
22+
23+
![new.png](../public/images/linuxdo/new.png)
24+
25+
信息输入完成后，点击下方蓝色的 ==`保存`== 按钮创建应用
26+
27+
![save.png](../public/images/linuxdo/save.png)
28+
29+
创建完成后，进入应用详情页
30+
31+
![secrets.png](../public/images/linuxdo/secrets.png)
32+
33+
记录 `Client ID`、`Client Secret`、`回调地址`，这三个东西在我们集成的时候都用得到，请妥善保管 ID 和 Secret

‎docs/clients/oschina.md

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

‎docs/clients/qq.md

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

‎docs/clients/wechat_mp.md

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

‎docs/clients/wechat_open.md

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

‎docs/clients/wechat_work.md

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

‎docs/clients/weibo.md

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

‎docs/explanation.md

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

‎docs/fastapi.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
提供的实用程序可简化 FastAPI 中 OAuth2 流程的集成
2+
3+
## `FastAPIOAuth20`
4+
5+
依赖关系可调用，用于处理授权回调，它读取查询参数并返回访问令牌和状态
6+
7+
```python
8+
from fastapi import FastAPI, Depends
9+
from fastapi_oauth20 import FastAPIOAuth20, LinuxDoOAuth20
10+
11+
client = LinuxDoOAuth20("CLIENT_ID", "CLIENT_SECRET")
12+
linuxdo_oauth2_callback = FastAPIOAuth20(client, "oauth2-callback")
13+
14+
app = FastAPI()
15+
16+
17+
@app.get("/oauth2-callback", name="oauth-callback")
18+
async def oauth2_callback(access_token_state=Depends(linuxdo_oauth2_callback)):
19+
token, state = access_token_state
20+
# Do something useful
21+
```
22+
23+
## 自定义异常
24+
25+
如果回调逻辑内部发生错误（用户拒绝访问、授权代码无效......），依赖关系将引发 `OAuth20AuthorizeCallbackError` 错误
26+
27+
它继承自 FastAPI 的 [HTTPException](https://fastapi.tiangolo.com/reference/exceptions/#fastapi.HTTPException)，因此默认的
28+
FastAPI 异常处理程序会自动对其进行处理。您可以通过为 `OAuth20AuthorizeCallbackError` 实现自己的异常处理程序来自定义此行为
29+
30+
```python
31+
from fastapi import FastAPI, Request
32+
from fastapi.responses import JSONResponse
33+
from fastapi_oauth20.integrations.fastapi import OAuth20AuthorizeCallbackError
34+
35+
app = FastAPI()
36+
37+
38+
@app.exception_handler(OAuth20AuthorizeCallbackError)
39+
async def oauth2_authorize_callback_error_handler(request: Request, exc: OAuth20AuthorizeCallbackError):
40+
detail = exc.detail
41+
status_code = exc.status_code
42+
return JSONResponse(
43+
status_code=status_code,
44+
content={"message": "The OAuth2 callback failed", "detail": detail},
45+
)
46+
```

‎docs/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
我们的目标是集成多个 CN 第三方客户端，敬请期待（🐦）...
1818

19-
你可以在 [集成状态](integration.md) 获取当前集成情况
19+
你可以在 [客户端状态](status.md) 获取当前集成情况
2020

2121
## 互动
2222

‎docs/install.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,20 @@
77

88
## 安装
99

10-
=== ":simple-piped: pip"
10+
=== ":simple-python: pip"
1111

1212
```sh
1313
pip install fastapi-oauth20
1414
```
1515

16-
=== ":simple-pdm: pdm"
16+
=== ":simple-uv: uv"
1717

1818
```sh
19-
pdm add fastapi-oauth20
19+
uv add fastapi-oauth20
2020
```
2121

22-
=== ":simple-uv: uv"
22+
=== ":simple-pdm: pdm"
2323

2424
```sh
25-
uv add fastapi-oauth20
25+
pdm add fastapi-oauth20
2626
```

‎docs/integration.md

-21
This file was deleted.

‎docs/public/images/github/dev.png

62 KB
Loading

‎docs/public/images/github/oauth.png

30 KB
Loading

‎docs/public/images/github/register.png

41.5 KB
Loading

‎docs/public/images/github/secrets.png

51.3 KB
Loading

‎docs/public/images/github/settings.png

38.7 KB
Loading

‎docs/public/images/linuxdo/connect.png

188 KB
Loading

‎docs/public/images/linuxdo/dev.png

45.4 KB
Loading

‎docs/public/images/linuxdo/new.png

19.4 KB
Loading

‎docs/public/images/linuxdo/save.png

25.9 KB
Loading

‎docs/public/images/linuxdo/secrets.png

30.3 KB
Loading

‎docs/status.md

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

‎mkdocs.yml

+33-10
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,29 @@ site_author: Wu Clan
66
repo_name: fastapi-oauth20
77
repo_url: https://github.com/wu-clan/fastapi-oauth20
88
nav:
9-
- Home:
10-
- 主页: index.md
11-
- 集成状态: integration.md
12-
- Install: install.md
13-
- Explanation: explanation.md
14-
- Usage: usage.md
15-
- Advanced: advanced.md
16-
- Changelog: changelog.md
9+
- 主页: index.md
10+
- 安装: install.md
11+
- 名词解释: explanation.md
12+
- 用法: usage.md
13+
- 高级用法: advanced.md
14+
- 集成:
15+
- FastAPI: fastapi.md
16+
- 客户端状态: status.md
17+
- 客户端申请:
18+
- LinuxDo: clients/linuxdo.md
19+
- GitHub: clients/github.md
20+
- Gitee: clients/gitee.md
21+
- 开源中国: clients/oschina.md
22+
- 微信小程序: clients/wechat_open.md
23+
- 微信开放平台: clients/wechat_mp.md
24+
- 企业微信二维码登录: clients/wechat_work.md
25+
- 飞书: clients/feishu.md
26+
- 钉钉: clients/dingding.md
27+
- QQ: clients/qq.md
28+
- 微博: clients/weibo.md
29+
- 抖音: clients/douyin.md
30+
- Google: clients/google.md
31+
- 变更日志: changelog.md
1732
theme:
1833
name: material
1934
font:
@@ -42,14 +57,14 @@ theme:
4257
- navigation.instant.progress
4358
- navigation.path
4459
- navigation.tracking
45-
- navigation.tabs
4660
- navigation.tabs.sticky
4761
- navigation.top
4862
- navigation.footer
4963
- search.suggest
5064
- toc.follow
5165
plugins:
5266
- search
67+
- glightbox
5368
markdown_extensions:
5469
- toc:
5570
permalink: true
@@ -58,9 +73,17 @@ markdown_extensions:
5873
- attr_list
5974
- def_list
6075
- md_in_html
61-
- pymdownx.snippets
76+
- admonition
77+
- pymdownx.details
6278
- pymdownx.superfences
79+
- pymdownx.snippets
6380
- pymdownx.inlinehilite
81+
- pymdownx.critic
82+
- pymdownx.caret
83+
- pymdownx.keys
84+
- pymdownx.mark
85+
- pymdownx.tilde
86+
- pymdownx.blocks.caption
6487
- pymdownx.highlight:
6588
anchor_linenums: true
6689
line_spans: __span

0 commit comments

Comments
 (0)