From 1f4e1dea752682ac98b573615b84616865514975 Mon Sep 17 00:00:00 2001 From: Tim Date: Thu, 18 Sep 2025 17:36:00 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20CONTRIBUTING.md=20=E6=96=B0=E5=A2=9E=20?= =?UTF-8?q?OpenAPI=20=E4=BB=8B=E7=BB=8D=20#923?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5eb8c925..211de899d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,6 +11,13 @@ - [配置环境变量](#配置环境变量-2) - [安装依赖和运行](#安装依赖和运行) - [其他配置](#其他配置) + - [配置第三方登录以GitHub为例](#配置第三方登录以GitHub为例) + - [配置Resend邮箱服务](#配置Resend邮箱服务) +- [API文档](#api文档) + - [OpenAPI文档](#openapi文档) + - [部署时间线以及文档时效性](#部署时间线以及文档时效性) + - [OpenAPI文档使用](#OpenAPI文档使用) + - [OpenAPI文档应用场景](#OpenAPI文档应用场景) ## 前置工作 @@ -209,7 +216,7 @@ npm run dev ## 其他配置 -### 配置第三方登录，这里以 GitHub 为例： +### 配置第三方登录以GitHub为例 - 修改 `application.properties` 配置 @@ -225,7 +232,7 @@ npm run dev ![github配置2](assets/contributing/github_img_2.png) -### 配置 Resend 邮箱服务 +### 配置Resend邮箱服务 https://resend.com/emails 创建账号并登录 @@ -246,6 +253,42 @@ https://resend.com/emails 创建账号并登录 `RESEND_API_KEY`：**刚刚复制的 Key** ![image-20250906151218330](assets/contributing/image-20250906151218330.png) -## 开源共建和API文档 +## API文档 +### OpenAPI文档 +https://docs.open-isle.com + +### 部署时间线以及文档时效性 + +我已经将API Docs的部署融合进本站CI & CD中，目前如下 + +- 每次合入main之后，都会构建预发环境 http://staging.open-isle.com/ ,现在文档是紧随其后进行部署，也就是说代码合入main之后，如果是新增后台接口，就可以立即通过OpenAPI文档页面进行查看和调试，但是如果想通过OpenAPI调试需要选择预发环境的 +- 每日凌晨三点会构建并重新部署正式环境，届时当日合入main的新后台API也可以通过OpenAPI文档页面调试 + +![CleanShot 2025-09-10 at 12 .04.48@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/168303009f4047ca828344957e911ff1.png) + +👆如图是合入main之后构建预发+docs的情形，总大约耗时4分钟左右 + +### OpenAPI文档使用 + +- 预发环境/正式环境切换，可以通过如下位置切换API环境 + +![CleanShot 2025-09-10 at 12 .08.00@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/f9fb7a0f020d4a0e94159d7820783224.png) + +- API分两种，一种是需要鉴权（需登录后的token），另一种是直接访问，可以直接访问的GET请求，直接点击Send即可调试，如下👇，比如本站的推荐流rss: /api/rss: https://docs.open-isle.com/openapi/feed + +![CleanShot 2025-09-10 at 12 .09.48@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/2afb42e0c96340559dd42854905ca5fc.png) + +- 需要登陆的API，比如关注，取消关注，发帖等，则需要提供token，目前在“API与调试”可获取自身token，可点击link看看👉 https://www.open-isle.com/about?tab=api + +![CleanShot 2025-09-10 at 12 .11.07@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/74033f1b9cc14f2fab3cbe3b7fe306d8.png) + +copy完token之后，粘贴到Bear之后, 即可发送调试， 如下👇，大家亦可自行尝试：https://docs.open-isle.com/openapi/me + +![CleanShot 2025-09-10 at 12 .13.00@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/63913fe2e70541a486651e35c723765e.png) + +#### OpenAPI文档应用场景 + +- 方便大部分前端调试的需求，如果有只想做前端/客户端的同学参与本项目，该平台会大大提高效率 +- 自动化：有自动化发帖/自动化操作的需求，亦可通过该平台实现或调试 - API文档: https://docs.open-isle.com/openapi