![cover](/upload/showDoc.png)
知识库私有化搭建-ShowDoc
先说结论:showDoc应该现阶段是小型团队或者家庭
文档or知识库私有化
的不二之选了。官方文档:点这里查看
showdoc 功能概览:
Docker安装
- 镜像选择:
star7th/showdoc
- 端口和文件映射配置如下:
- 日志配置:
启动镜像后,打开showdoc页面,选择完成语言后,会给一个默认用户名和密码,登录进去后记得修改哈!
登录后页面默认有如下内容:
我们会看到4个例子,选择 技术团队文档示例 可以查看 markdown
语法和plantuml
语法。
文档写作
文档协作主要以 markdown 为主,也可以创建Excel表格,同时还支持plantuml,包括时序图、用例图、类图、组件图、状态图等等。
搭建好后,可以看到很多文档的例子,照着看一些就学会了,很简单的!
showDoc管理
团队管理
可以进行以团队为单位的管理,每个团队有不同的文档权限,互不干扰!同时一个用户也可以在某几个团队中任职,管理多个团队的文档数据。
项目管理
将文档以项目的形式进行管理,每个项目可以分配给不用的团队
后台管理
后台管理可以对 人员、项目、附件、站点进行管理和配置
文档生成
API 文档生成
- showdoc 官方提供了一种自动化生成接口和文档的方案。在代码里编写特定格式的程序注释,然后程序就可以通过读取这些注释来自动生成文档。由于这种方式不跟特定的语言耦合,因此它的使用范围相当广泛,可以支持
c++
、java
、php
、node
等等常见的主流语言。- 采用这种方式,尽管我们在第一次填写注释的时候可能会有些繁琐,但是它后期带来的可维护性是非常高的。代码变动后,不需要再额外登录 showdoc,直接在代码里修改注释即可。同时自动化的脚本也可以加入持续集成或者某些自动化工程里,让“写接口和文档”这件事如”单元测试”般纳入工程工作流里面。
以 windows 下的操作为例
windows无法直接运行sh脚本,需要额外下载软件。
- 下载
git for windows
; - 下载showdoc官方脚本;
- 将
showdoc_api.sh
放在项目目录下,编辑脚本中的api_key
和api_token
,如果自建服务,再编辑一下url地址
; - 搞定上面3项后,然后直接双击运行,脚本会自动递归本目录和子目录的所有文本代码文件,生成的文档会放进 api_key 所指向的这个项目里。
注意:代码注释要使用 showdoc 规范
/**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户登录
* @description 用户登录的接口
* @method get
* @url https://www.showdoc.cc/home/user/login
* @header token 可选 string 设备token
* @param username 必选 string 用户名
* @param password 必选 string 密码
* @param name 可选 string 用户昵称
* @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
* @return_param groupid int 用户组id
* @return_param name string 用户昵称
* @remark 这里是备注信息
* @number 99
*/
数据字典生成
和生成API类似,需要先下载指定脚本文件,之后修改配置信息,最后执行脚本命令!
链接分享
可以将单篇文章或者笔记以链接的形式分享给客户,非常方便:
本文是原创文章,采用 CC BY-NC-ND 4.0 协议,完整转载请注明来自 青柠Loft-青柠炸机站
评论
匿名评论
隐私政策
你无需删除空行,直接评论以获取最佳展示效果