add some docs

2 years ago · e9462c6270
parent f2d674c62e
commit e9462c6270
16 changed files with 166 additions and 9 deletions
--- a/README.md
+++ b/README.md
@ -239,11 +239,20 @@ docker compose up --build
 > 注意：默认提供的 docker-compose.yaml 初衷是搭建本机开发调试环境，如果需要产品部署供外网访问，请自行调优配置参数或使用其他方式部署。

 ### API 文档
-构建时将 `docs` 添加到TAGS中:
+* `config.yaml` 添加 `Docs:OpenAPI` 功能项:
+```yaml
+...
+Features:
+  Default: ["Base", "MySQL", "Option", "LocalOSS", "LoggerFile", "Docs"]
+  Docs: ["Docs:OpenAPI"]
+...
+```
+
+* 构建时将 `docs` 添加到TAGS中:
 ```sh
 make run TAGS='docs'

-# visit http://127.0.0.1:8008/docs
+# visit http://127.0.0.1:8008/docs/openapi
 ```

 ### 配置说明
@ -326,7 +335,9 @@ release/paopao-ce --no-default-features --features sqlite3,localoss,loggerfile,r
 * 支付: Alipay   
  `Alipay`  开启基于[支付宝开放平台](https://open.alipay.com/)的钱包功能；   
 * 短信验证码: SmsJuhe(需要开启sms)    
-  `Sms` 开启短信验证码功能，用于手机绑定验证手机是否注册者的；功能如果没有开启，手机绑定时任意短信验证码都可以绑定手机；     
+  `Sms` 开启短信验证码功能，用于手机绑定验证手机是否注册者的；功能如果没有开启，手机绑定时任意短信验证码都可以绑定手机；
+* 开发文档: Docs:OpenAPI
+  `Docs:OpenAPI` 开启openapi文档功能，提供web api文档说明(visit http://127.0.0.1:8008/docs/openapi)；        
 * 其他: PhoneBind/OSS:Retention/OSS:TempDir     
  `PhoneBind` 手机绑定功能；     
  `OSS:Retention` 基于对象存储系统的对象过期自动删除特性实现 先创建临时对象再持久化的功能(目前状态: 内测阶段)；  
--- a/config.yaml.sample
+++ b/config.yaml.sample
@ -16,6 +16,7 @@ Features:
  Demo: ["Base", "MySQL", "Option", "Zinc", "Sms", "MinIO", "LoggerZinc", "Migration"]
  Slim: ["Base", "Sqlite3", "LocalOSS", "LoggerFile", "OSS:TempDir"]
  Base: ["Redis", "PhoneBind"]
+  Docs: ["Docs:OpenAPI"]
  Option: ["SimpleCacheIndex"]
  Sms: "SmsJuhe"
 SmsJuhe:
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,6 @@
+## 开发文档
+本目录包含一些开发者文档。
+
+* [openapi](openapi): api相关文档
+* [proposal](proposal): 开发/设计 提按相关文档
+* [deploy](deploy): 部署相关文档
--- a/docs/assets/rapidoc-min.js.map
+++ b/docs/assets/rapidoc-min.js.map
--- a/docs/deploy/README.md
+++ b/docs/deploy/README.md
@ -0,0 +1,2 @@
+## 部署文档
+TODO
--- a/docs/openapi/assets/rapidoc-min.js
+++ b/docs/openapi/assets/rapidoc-min.js
--- a/docs/openapi/embed.go
+++ b/docs/openapi/embed.go
@ -1,7 +1,7 @@
 //go:build docs
 // +build docs

-package docs
+package openapi

 import (
 	"embed"
--- a/docs/openapi/index.html
+++ b/docs/openapi/index.html
@ -8,12 +8,12 @@
    <!-- Important: rapi-doc uses utf8 charecters -->
    <script
      type="module"
-      src="/docs/assets/rapidoc-min.js"
+      src="/docs/openapi/assets/rapidoc-min.js"
    ></script>
  </head>
  <body>
    <rapi-doc
-      spec-url="/docs/openapi.json"
+      spec-url="/docs/openapi/openapi.json"
      render-style="read"
    >
    </rapi-doc>
--- a/docs/openapi/openapi.json
+++ b/docs/openapi/openapi.json
--- a/docs/proposal/.proposal.md
+++ b/docs/proposal/.proposal.md
@ -0,0 +1,26 @@
+| 编号 | 作者 | 发表时间 | 变更时间 | 版本 | 状态 |
+| ----- | ----- | ----- | ----- | ----- | ----- |
+| 000 | 北野 | 2022-11-04 |2022-11-04 | v1.0| 提议 |
+
+## <我是标题>
+ ---- 这里写简要介绍 ----
+ 
+## 场景
+
+ ---- 这里描述在什么使用场景下会需要本提按 ----
+
+## 需求
+
+ ---- 这里表述具体需求，在上面描述的场景下，我们需要获得的具体状态 ----
+ 
+## 方案
+
+ ---- 这里提出可能的解决方案 ----
+ 
+## 疑问
+
+ ---- 这里描述上述内容中的疑问，比如方案落地将会遇到的坑，其他方案与本文档的比较 ----
+ 
+## 更新记录
+#### v1.0(2022-11-04) - 北野
+* 初始文档
--- a/docs/proposal/001-关于paopao-ce的设计定位.md
+++ b/docs/proposal/001-关于paopao-ce的设计定位.md
@ -0,0 +1,11 @@
+| 编号 | 作者 | 发表时间 | 变更时间 | 版本 | 状态 |
+| ----- | ----- | ----- | ----- | ----- | ----- |
+| 001| 北野 | 2022-11-04 | 2022-11-04 | v0.0 | 提议 |
+
+## 概述
+
+TODO
+ 
+## 更新记录
+#### v0.0(2022-11-04) - 北野
+* 初始文档,先占个位置
--- a/docs/proposal/002-关于Friendship功能项的设计.md
+++ b/docs/proposal/002-关于Friendship功能项的设计.md
@ -0,0 +1,38 @@
+| 编号 | 作者 | 发表时间 | 变更时间 | 版本 | 状态 |
+| ----- | ----- | ----- | ----- | ----- | ----- |
+| 002| 北野 | 2022-11-04 | 2022-11-04 | v0.1 | 提议 |
+
+## 关于Friendship功能项的设计
+ ---- 这里写简要介绍 ----
+
+## 场景
+
+ ---- 这里描述在什么使用场景下会需要本提按 ----
+
+## 需求
+
+建立一个类似于微信朋友圈的弱关系好友体系，使得用户可以控制每一条推文的授权访问(公开/私密/好友可见)。
+ 
+## 方案
+
+#### 设计要点
+* 建立好友体系，提供添加/解除好友关系的机制；
+* 浏览好友列表的机制；
+* 发送推文时可以设置推文的访问权限(可见性设置)；
+* 推文展示时标记推文的可见性描述；
+
+#### 设计细节
+
+TODO
+
+## 疑问
+
+1. 什么是弱关系好友体系？如何形成这种好友体系？ 
+TODO
+
+2. 如何开启这个功能？
+TODO
+
+## 更新记录
+#### v0.1(2022-11-04) - 北野
+* 初始文档
--- a/docs/proposal/003-关于Followship功能项的设计.md
+++ b/docs/proposal/003-关于Followship功能项的设计.md
@ -0,0 +1,27 @@
+| 编号 | 作者 | 发表时间 | 变更时间 | 版本 | 状态 |
+| ----- | ----- | ----- | ----- | ----- | ----- |
+| 003| 北野 | 2022-11-04 | 2022-11-04 | v0.0 | 提议 |
+
+## 关于Followship功能项的设计
+ ---- 这里写简要介绍 ----
+
+## 场景
+
+ ---- 这里描述在什么使用场景下会需要本提按 ----
+
+## 需求
+实现类似于Twitter的追随者关注模式的推文传播模型，使得广场页面可以浏览已关注用户的推文。
+TODO-TL;DR...
+ 
+## 方案
+
+TODO
+
+## 疑问
+
+1. 如何开启这个功能？
+TODO
+
+## 更新记录
+#### v0.0(2022-11-04) - 北野
+* 初始文档， 先占个位置
--- a/docs/proposal/README.md
+++ b/docs/proposal/README.md
@ -0,0 +1,4 @@
+## Draft
+* [001-关于paopao-ce的设计定位](001-关于paopao-ce的设计定位.md "关于paopao-ce的设计定位")
+* [002-关于Friendship功能项的设计](002-关于Friendship功能项的设计.md "关于Friendship功能项的设计")
+* [003-关于Followship功能项的设计](003-关于Followship功能项的设计.md "关于Followship功能项的设计")
--- a/docs/proposal/提案模板.md
+++ b/docs/proposal/提案模板.md
@ -0,0 +1,29 @@
+| 编号 | 作者 | 发表时间 | 变更时间 | 版本 | 状态 |
+| ----- | ----- | ----- | ----- | ----- | ----- |
+| <编号000> | <作者> | <发表时间> | <变更时间> | <版本号v1.0> | <提议/提案/决议/冻结> |
+
+* 编号： 填写提案编号，三位数，比如001。
+* 作者： 填写发表者。
+* 发表时间： 填写首次发表时间，之后保持不变。
+* 变更时间： 填写变更时间，首次发表时，变更时间和发表时间一样。
+* 版本： 当前文档版本号， 样式为v1.0/v2.0 保持两位数，微调加次版本号， 大调加大版本号。
+* 状态： 首次发表 状态为 **提议**； 经过讨论，多数人认同，状态为 **提案**; 审议通过，决定对方案落地，状态为 **决议**; 审议未通过，方案暂时不落地，状态变更为 **冻结**。
+
+## <我是标题>
+ ---- 这里写简要介绍 ----
+ 
+## 场景
+
+ ---- 这里描述在什么使用场景下会需要本提按 ----
+
+## 需求
+
+ ---- 这里表述具体需求，在上面描述的场景下，我们需要获得的具体状态 ----
+ 
+## 方案
+
+ ---- 这里提出可能的解决方案 ----
+ 
+## 疑问
+
+ ---- 这里描述上述内容中的疑问，比如方案落地将会遇到的坑，其他方案与本文档的比较 ----
--- a/internal/routers/docs_embed.go
+++ b/internal/routers/docs_embed.go
@ -5,10 +5,13 @@ package routers

 import (
 	"github.com/gin-gonic/gin"
-	"github.com/rocboss/paopao-ce/docs"
+	"github.com/rocboss/paopao-ce/docs/openapi"
+	"github.com/rocboss/paopao-ce/internal/conf"
 )

 // registerDocs register docs asset route
 func registerDocs(e *gin.Engine) {
-	e.StaticFS("/docs", docs.NewFileSystem())
+	if conf.CfgIf("Docs:OpenAPI") {
+		e.StaticFS("/docs/openapi", openapi.NewFileSystem())
+	}
 }