diff --git a/README.en-US.md b/README.en-US.md
index c4d7a3b..6cdde7f 100644
--- a/README.en-US.md
+++ b/README.en-US.md
@@ -170,6 +170,18 @@ authRequest.login(callback);
I look forward to your joining us.
+
+## Contributors
+
+[contributors](https://docs.justauth.whnb.wang/#/contributors)
+
+## Recommend
+
+- `spring-boot-demo` In-depth study and actual combat of spring boot projects: [https://github.com/xkcoding/spring-boot-demo](https://github.com/xkcoding/spring-boot-demo)
+- `mica` Efficient Development of scaffolding by Spring Cloud: [https://github.com/lets-mica/mica](https://github.com/lets-mica/mica)
+- `pig` Cosmic strongest Micro Services Certified authorized scaffolding (essential for Architects): [https://gitee.com/log4j/pig](https://gitee.com/log4j/pig)
+- `SpringBlade` Complete online solution (necessary for enterprise development): https://gitee.com/smallc/SpringBlade
+
## References
- [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
diff --git a/README.md b/README.md
index 6f66382..bd442e2 100644
--- a/README.md
+++ b/README.md
@@ -187,11 +187,17 @@ _请知悉:经咨询CSDN官方客服得知,CSDN的授权开放平台已经
在项目立项初期,也对当前开源圈的一些相同类型的项目作过调研,同时本项目也参考过这些项目,再次感谢开源圈内的朋友。
-[YurunOAuthLogin](https://gitee.com/yurunsoft/YurunOAuthLogin): PHP 第三方登录授权 SDK
+- [YurunOAuthLogin](https://gitee.com/yurunsoft/YurunOAuthLogin): PHP 第三方登录授权 SDK
+- [阿里妈妈MUX倾力打造的矢量图标库-iconfont](https://www.iconfont.cn/search/index): 本文档中的图标大部分取自该平台
+- [mica](https://github.com/lets-mica/mica):Spring Cloud 微服务开发核心包,支持 `web `和 `webflux`。注:JustAuth项目中的[UuidUtils](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/utils/UuidUtils.java)就是直接使用的mica提供的高性能的uuid创建工具类源码[StringUtil.java](https://github.com/lets-mica/mica/blob/master/mica-core/src/main/java/net/dreamlu/mica/core/utils/StringUtil.java#L335)
+- 感谢 JetBrains 提供的免费开源 License:
+
-[阿里妈妈MUX倾力打造的矢量图标库-iconfont](https://www.iconfont.cn/search/index): 本文档中的图标大部分取自该平台
-
-[mica](https://github.com/lets-mica/mica):Spring Cloud 微服务开发核心包,支持 `web `和 `webflux`。注:JustAuth项目中的[UuidUtils](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/utils/UuidUtils.java)就是直接使用的mica提供的高性能的uuid创建工具类源码[StringUtil.java](https://github.com/lets-mica/mica/blob/master/mica-core/src/main/java/net/dreamlu/mica/core/utils/StringUtil.java#L335)
+## 开源推荐
+- `spring-boot-demo` 深度学习并实战 spring boot 的项目: [https://github.com/xkcoding/spring-boot-demo](https://github.com/xkcoding/spring-boot-demo)
+- `mica` SpringBoot 微服务高效开发工具集: [https://github.com/lets-mica/mica](https://github.com/lets-mica/mica)
+- `pig` 宇宙最强微服务认证授权脚手架(架构师必备): [https://gitee.com/log4j/pig](https://gitee.com/log4j/pig)
+- `SpringBlade` 完整的线上解决方案(企业开发必备): https://gitee.com/smallc/SpringBlade
## 关于OAuth
@@ -210,7 +216,6 @@ _请知悉:经咨询CSDN官方客服得知,CSDN的授权开放平台已经
- 开源总群 (190886500):各个开源项目的都有,也有博客建设等方面的朋友。
-
## 请喝咖啡
| 支付宝 | 微信 |
diff --git a/docs/README.md b/docs/README.md
index a59bc6c..8d9f7a6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -155,6 +155,11 @@ JustAuth一共有两个主要分支:
- 线上版分支(master):稳定版,发布版就是这个分支的代码
- 开发版分支(dev):不保证稳定,新功能都会优先推送到该分支,对于想尝鲜的朋友,可以直接下载代码,然后源码编译dev分支
+## 开源推荐
+- `spring-boot-demo` 深度学习并实战 spring boot 的项目: [https://github.com/xkcoding/spring-boot-demo](https://github.com/xkcoding/spring-boot-demo)
+- `mica` SpringBoot 微服务高效开发工具集: [https://github.com/lets-mica/mica](https://github.com/lets-mica/mica)
+- `pig` 宇宙最强微服务认证授权脚手架(架构师必备): [https://gitee.com/log4j/pig](https://gitee.com/log4j/pig)
+- `SpringBlade` 完整的线上解决方案(企业开发必备): https://gitee.com/smallc/SpringBlade
## 捐赠
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 1f3e049..deb1e5c 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -2,13 +2,13 @@
- [贡献者名单](contributors.md)
- 快速开始
- [名词解释](explain.md)
+ - [OAuth流程](oauth.md)
- [如何使用](how-to-use.md)
- - [获取授权链接](authorize.md)
- - [登录](login.md)
- 其他特性
- [使用State](using-state.md)
- [自定义state缓存](customize-the-state-cache.md)
- [配套项目](supporting.md)
- [Q&A](Q&A.md)
- [Who is using](users.md)
+- [致谢](thx.md)
- [更新记录](update.md)
diff --git a/docs/authorize.md b/docs/authorize.md
deleted file mode 100644
index 832d17f..0000000
--- a/docs/authorize.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# 获取授权链接
-
-待补充
diff --git a/docs/explain.md b/docs/explain.md
index cb7d57e..56f9525 100644
--- a/docs/explain.md
+++ b/docs/explain.md
@@ -2,7 +2,7 @@
## 本文相关名词
-- `调用者` 指使用`JustAuth`的开发者
+- `开发者` 指使用`JustAuth`的开发者
- `第三方` 指开发者对接的第三方网站,比如:QQ平台、微信平台、微博平台
- `用户` 指最终服务的真实用户
@@ -12,9 +12,9 @@
- `clientId` 客户端身份标识符(应用id),一般在申请完Oauth应用后,由**第三方平台颁发**,唯一
- `clientSecret` 客户端密钥,一般在申请完Oauth应用后,由**第三方平台颁发**
-- `redirectUri` **调用者项目中的有效api地址**。用户在确认第三方平台授权(登录)后,第三方平台会重定向到该地址,并携带code等参数
-- `state` 用来保持授权会话流程完整性,防止CSRF攻击的安全的随机的参数,由**调用者生成**
-- `alipayPublicKey` 支付宝公钥。当选择支付宝登录时,必传该值,由**调用者生成**
+- `redirectUri` **开发者项目中的有效api地址**。用户在确认第三方平台授权(登录)后,第三方平台会重定向到该地址,并携带code等参数
+- `state` 用来保持授权会话流程完整性,防止CSRF攻击的安全的随机的参数,由**开发者生成**
+- `alipayPublicKey` 支付宝公钥。当选择支付宝登录时,必传该值,由**开发者生成**
- `unionId` 是否需要申请unionid,目前只针对**qq登录**。注:qq授权登录时,获取unionid需要单独发送邮件申请权限。如果个人开发者账号中申请了该权限,可以将该值置为true,在获取openId时就会同步获取unionId。参考链接:[UnionID介绍](http://wiki.connect.qq.com/unionid%E4%BB%8B%E7%BB%8D)
- `stackOverflowKey` Stack Overflow 登陆时需单独提供的key,由**第三方平台颁发**
- `agentId` 企业微信登陆时需单独提供该值,由**第三方平台颁发**,为授权方的网页应用ID
diff --git a/docs/how-to-use.md b/docs/how-to-use.md
index 6d67086..0dff3f1 100644
--- a/docs/how-to-use.md
+++ b/docs/how-to-use.md
@@ -1,13 +1,18 @@
+# 如何使用
+
在前面有介绍到,JustAuth的特点之一就是**简**,极简主义,不给使用者造成不必要的障碍。
既然牛皮吹下了, 那么如何才能用JustAuth实现第三方登录呢?
+## 使用步骤
+
使用JustAuth总共分三步(**这三步也适合于JustAuth支持的任何一个平台**):
1. 申请注册第三方平台的开发者账号
2. 创建第三方平台的应用,获取配置信息(`accessKey`, `secretKey`, `redirectUri`)
3. 使用该工具实现授权登陆
+## 使用方式
- 引入依赖
```xml
@@ -30,4 +35,114 @@ authRequest.authorize("state");
// 授权登录后会返回code(auth_code(仅限支付宝))、state,1.8.0版本后,可以用AuthCallback类作为回调接口的参数
// 注:JustAuth默认保存state的时效为3分钟,3分钟内未使用则会自动清除过期的state
authRequest.login(callback);
+```
+
+## API分解
+
+**JustAuth**的核心就是一个个的`request`,每个平台都对应一个具体的`request`类,所以在使用之前,需要就具体的授权平台创建响应的`request`
+
+```java
+// 创建授权request
+AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder()
+ .clientId("clientId")
+ .clientSecret("clientSecret")
+ .redirectUri("redirectUri")
+ .build());
+```
+
+所有可用的`Request`列表请参考:[已集成的平台](https://docs.justauth.whnb.wang/#/README?id=已集成的平台)
+
+### 获取授权链接
+
+```java
+String authorizeUrl = authRequest.authorize("state");
+```
+获取到`authorizeUrl`后,可以手动实现redirect到`authorizeUrl`上
+
+**伪代码**
+
+```java
+/**
+ *
+ * @param source 第三方授权平台,以本例为参考,该值为gitee(因为上面声明的AuthGiteeRequest)
+ */
+@RequestMapping("/render/{source}")
+public void renderAuth(@PathVariable("source") String source, HttpServletResponse response) throws IOException {
+ AuthRequest authRequest = getAuthRequest(source);
+ String authorizeUrl = authRequest.authorize(AuthStateUtils.createState());
+ response.sendRedirect(authorizeUrl);
+}
+```
+
+注:`state`建议必传!`state`在`OAuth`的流程中的主要作用就是保证请求完整性,防止**CSRF**风险,此处传的`state`将在回调时传回
+
+### 登录(获取用户信息)
+
+```java
+AuthResponse response = authRequest.login(callback);
+```
+
+授权登录后会返回code(auth_code(仅限支付宝)、authorization_code(仅限华为))、state,1.8.0版本后,用`AuthCallback`类作为回调接口的入参
+
+**伪代码**
+
+```java
+/**
+ *
+ * @param source 第三方授权平台,以本例为参考,该值为gitee(因为上面声明的AuthGiteeRequest)
+ */
+@RequestMapping("/callback/{source}")
+public Object login(@PathVariable("source") String source, AuthCallback callback) {
+ AuthRequest authRequest = getAuthRequest(source);
+ AuthResponse response = authRequest.login(callback);
+ return response;
+}
+```
+
+**注:第三方平台中配置的授权回调地址,以本文为例,在创建授权应用时的回调地址应为:`[host]/callback/gitee`**
+
+### 刷新token
+
+注:`refresh`功能,并不是每个平台都支持
+
+```java
+AuthResponse response = authRequest.refresh(AuthToken.builder().refreshToken(token).build());
+```
+
+**伪代码**
+
+```java
+/**
+ *
+ * @param source 第三方授权平台,以本例为参考,该值为gitee(因为上面声明的AuthGiteeRequest)
+ * @param token login成功后返回的refreshToken
+ */
+@RequestMapping("/refresh/{source}")
+public Object refreshAuth(@PathVariable("source") String source, String token){
+ AuthRequest authRequest = getAuthRequest(source);
+ return authRequest.refresh(AuthToken.builder().refreshToken(token).build());
+}
+```
+
+### 取消授权
+
+注:`revoke`功能,并不是每个平台都支持
+
+```java
+AuthResponse response = authRequest.revoke(AuthToken.builder().accessToken(token).build());
+```
+
+**伪代码**
+
+```java
+/**
+ *
+ * @param source 第三方授权平台,以本例为参考,该值为gitee(因为上面声明的AuthGiteeRequest)
+ * @param token login成功后返回的accessToken
+ */
+@RequestMapping("/revoke/{source}/{token}")
+public Object revokeAuth(@PathVariable("source") String source, @PathVariable("token") String token) throws IOException {
+ AuthRequest authRequest = getAuthRequest(source);
+ return authRequest.revoke(AuthToken.builder().accessToken(token).build());
+}
```
\ No newline at end of file
diff --git a/docs/login.md b/docs/login.md
deleted file mode 100644
index 0aa4cb1..0000000
--- a/docs/login.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# 登录
-
-待补充
diff --git a/docs/oauth.md b/docs/oauth.md
new file mode 100644
index 0000000..7c36f2c
--- /dev/null
+++ b/docs/oauth.md
@@ -0,0 +1,61 @@
+# 关于OAuth
+
+请先查阅以下资料:
+
+- [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
+- [OAuth 2.0](https://oauth.net/2/)
+
+## OAuth 2的授权流程
+
+### 参与的角色
+
+- `Resource Owner` 资源所有者,即代表授权客户端访问本身资源信息的用户(User),也就是应用场景中的“**开发者A**”
+- `Resource Server` 资源服务器,托管受保护的**用户账号信息**,比如Github
+- `Authorization Server` 授权服务器,**验证用户身份**然后为客户端派发资源访问令牌,比如Github
+ - `Resource Server`和`Authorization Server` 可以是同一台服务器,也可以是不同的服务器,视具体的授权平台而有所差异
+- `Client` 客户端,即代表意图访问受限资源的**第三方应用**
+
+### 授权流程
+```html
+ +--------+ +---------------+
+ | |--(A)- Authorization Request ->| Resource |
+ | | | Owner |
+ | |<-(B)-- Authorization Grant ---| |
+ | | +---------------+
+ | |
+ | | +---------------+
+ | |--(C)-- Authorization Grant -->| Authorization |
+ | Client | | Server |
+ | |<-(D)----- Access Token -------| |
+ | | +---------------+
+ | |
+ | | +---------------+
+ | |--(E)----- Access Token ------>| Resource |
+ | | | Server |
+ | |<-(F)--- Protected Resource ---| |
+ +--------+ +---------------+
+```
+
+上面的流程图取自[The OAuth 2.0 Authorization Framework#1.2](https://tools.ietf.org/html/rfc6749#section-1.2)
+
+- (A) 用户打开**客户端**以后,**客户端**要求**用户**给予授权。
+- (B) **用户**同意给予**客户端**授权。
+- (C) **客户端**使用上一步获得的授权,向**认证服务器**申请令牌。
+- (D) **认证服务器**对**客户端**进行认证以后,确认无误,同意发放令牌
+- (E) **客户端**使用令牌,向**资源服务器**申请获取资源。
+- (F) **资源服务器**确认令牌无误,同意向**客户端**开放资源。
+
+### 授权许可 `Authorization Grant`
+
+- Authorization Code
+ - 结合普通服务器端应用使用(**web**端常用的授权方式)
+- Implicit
+ - 结合移动应用或 Web App 使用
+- Resource Owner Password Credentials
+ - 适用于受信任客户端应用,例如同个组织的内部或外部应用
+- Client Credentials
+ - 适用于客户端调用主服务API型应用(比如百度API Store)
+
+在`JustAuth`中是使用的`Authorization Code`授权方式,下面将主要讲解`Authorization Code`的授权流程
+
+(未完待续)
\ No newline at end of file
diff --git a/docs/thx.md b/docs/thx.md
new file mode 100644
index 0000000..777b037
--- /dev/null
+++ b/docs/thx.md
@@ -0,0 +1,15 @@
+# 致谢
+
+在项目立项初期,也对当前开源圈的一些相同类型的项目作过调研,同时本项目也参考过这些项目,再次感谢开源圈内的朋友。
+
+- [YurunOAuthLogin](https://gitee.com/yurunsoft/YurunOAuthLogin): PHP 第三方登录授权 SDK
+- [阿里妈妈MUX倾力打造的矢量图标库-iconfont](https://www.iconfont.cn/search/index): 本文档中的图标大部分取自该平台
+- [mica](https://github.com/lets-mica/mica):Spring Cloud 微服务开发核心包,支持 `web `和 `webflux`。注:JustAuth项目中的[UuidUtils](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/utils/UuidUtils.java)就是直接使用的mica提供的高性能的uuid创建工具类源码[StringUtil.java](https://github.com/lets-mica/mica/blob/master/mica-core/src/main/java/net/dreamlu/mica/core/utils/StringUtil.java#L335)
+
+
+**感谢 JetBrains 提供的免费开源 License**
+
+
+
+