From db3f7da181d87619a648f885fb71cf82472ad1df Mon Sep 17 00:00:00 2001 From: "yadong.zhang" Date: Fri, 13 Aug 2021 18:26:23 +0800 Subject: [PATCH] :memo: Writing docs. --- README.en-US.md | 93 ++++++++++++++++++++++++++++++++++++++++--------- README.md | 8 +++-- 2 files changed, 82 insertions(+), 19 deletions(-) diff --git a/README.en-US.md b/README.en-US.md index 5d3bddd..f51ccef 100644 --- a/README.en-US.md +++ b/README.en-US.md @@ -8,6 +8,9 @@ + + + @@ -49,33 +52,27 @@ Docs：[Reference Doc](https://justauth.wiki) ## Quick start -- Add maven dependency +### Add maven dependency + +- Add JustAuth dependency These artifacts are available from Maven Central: ```xml me.zhyd.oauth JustAuth - 1.16.3 + {latest-version} ``` -- Using JustAuth -```java -// Create authorization request -AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder() - .clientId("clientId") - .clientSecret("clientSecret") - .redirectUri("redirectUri") - .build()); -// Generate authorization url -authRequest.authorize("state"); -// After authorization to login, it will return: code(auth_code(Alipay only)),state, After version 1.8.0, you can use the AuthCallback as a parameter to the callback interface -// Note: JustAuth saves state for 3 minutes by default. If it is not used within 3 minutes, the expired state will be cleared automatically. -authRequest.login(callback); -``` -Note, that since [v1.14.0](https://gitee.com/yadong.zhang/JustAuth/releases/v1.14.0) JustAuth has been integrated by default with [simple-http](https://github.com/xkcoding/simple-http) as the HTTP general interface (see the update [JustAuth 1.14.0 release! Perfect decoupling of HTTP tools](https://mp.weixin.qq.com/s?__biz=MzA3NDk3OTIwMg==&mid=2450633197&idx=1&sn=11e625b307db62b2f1c4e82f7744b2a2&chksm=88929300bfe51a16562b45592a264482ae2c74c6dbfa4a3aa9611ad4fea4a9be5b1f0545527d&token=1093833287&lang=zh_CN#rd)). Since most projects already integrate HTTP tools such as OkHttp3, apache HttpClient, and hutool-http), in order to reduce unnecessary dependencies,Starting from [v1.14.0](https://gitee.com/yadong.zhang/JustAuth/releases/v1.14.0), JustAuth will not integrate hutool-http by default. If the developer's project is new or there is no integrated HTTP implementation tool in the project, please add the corresponding HTTP implementation class by yourself. Alternative dependencies are as follows: +> **latest-version** ： +> - CURRENT: ![](https://img.shields.io/github/v/release/justauth/JustAuth?style=flat-square) +> - SNAPSHOT: ![](https://img.shields.io/nexus/s/https/oss.sonatype.org/me.zhyd.oauth/JustAuth.svg?style=flat-square) + +- Add http dependency（Only need one） + +> If there is already in the project, please ignore it. In addition, you need to pay special attention. If the low version of the dependency has been introduced in the project, please exclude the low version of the dependency first, and then introduce the high version or the latest version of the dependency - hutool-http @@ -107,6 +104,68 @@ Note, that since [v1.14.0](https://gitee.com/yadong.zhang/JustAuth/releases/v1.1 ``` + +### Using JustAuth API + +#### Simple + +```java +// Create authorization request +AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder() + .clientId("clientId") + .clientSecret("clientSecret") + .redirectUri("redirectUri") + .build()); +// Generate authorization page url +authRequest.authorize("state"); +// Get token and userinfo +authRequest.login(callback); +``` + +#### Builder 1. Use unchanging `AuthConfig` + +```java +// Create authorization request +AuthRequest authRequest = AuthRequestBuilder.builder() + .source("github") + .authConfig(AuthConfig.builder() + .clientId("clientId") + .clientSecret("clientSecret") + .redirectUri("redirectUri") + .build()) + .build(); +``` + +#### Builder 2. Use dynamic `AuthConfig` + +```java +// Create authorization request +AuthRequest authRequest = AuthRequestBuilder.builder() + .source("gitee") + .authConfig((source) -> { + // Use source to dynamically get AuthConfig + // Here you can flexibly take the configuration from sql or take the configuration from the configuration file + return AuthConfig.builder() + .clientId("clientId") + .clientSecret("clientSecret") + .redirectUri("redirectUri") + .build(); + }) + .build(); +``` + +#### Builder 3. Support custom platform + +```java +AuthRequest authRequest = AuthRequestBuilder.builder() + // Key point: configure the custom implementation of AuthSource + .extendSource(AuthExtendSource.values()) + // Enum name in AuthExtendSource + .source("other") + // ... Do other things + .build(); +``` + ## Contributions 1. Fork this project to your repository diff --git a/README.md b/README.md index 55c8a10..df51073 100644 --- a/README.md +++ b/README.md @@ -69,11 +69,15 @@ JustAuth 集成了诸如：Github、Gitee、支付宝、新浪微博、微信、 me.zhyd.oauth JustAuth - 1.16.3 + {latest-version} ``` -如下**任选一种** HTTP 工具 依赖，_项目内如果已有，请忽略。另外需要特别注意，如果项目中已经引入了低版本的依赖，请先排除低版本依赖后，引入高版本或者最新版本的依赖_ +> **latest-version** 可选： +> - 稳定版：![](https://img.shields.io/github/v/release/justauth/JustAuth?style=flat-square) +> - 快照版：![](https://img.shields.io/nexus/s/https/oss.sonatype.org/me.zhyd.oauth/JustAuth.svg?style=flat-square) + +如下**任选一种** HTTP 工具 依赖，_项目内如果已有，请忽略。另外需要特别注意，如果项目中已经引入了低版本的依赖，请先排除低版本依赖后，再引入高版本或者最新版本的依赖_ - hutool-http -- GitLab