知识库私有化搭建-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脚本，需要额外下载软件。

1. 下载 git for windows；
2. 下载showdoc官方脚本；
3. 将showdoc_api.sh放在项目目录下，编辑脚本中的api_key 和 api_token，如果自建服务，再编辑一下url地址；
4. 搞定上面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类似，需要先下载指定脚本文件，之后修改配置信息，最后执行脚本命令！

链接分享

可以将单篇文章或者笔记以链接的形式分享给客户，非常方便：