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
 ```
 ### 配置说明
@ -327,6 +336,8 @@ release/paopao-ce --no-default-features --features sqlite3,localoss,loggerfile,r
  `Alipay`  开启基于[支付宝开放平台](https://open.alipay.com/)的钱包功能；   
 * 短信验证码: SmsJuhe(需要开启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())
 	}
 }