SelfHostSelfHost

ShowDoc：程序员写文档的必备工具

a year ago

ShowDoc是什么？

你有没有遇到过这种情况：接手别人的项目，打开代码一看，密密麻麻全是没注释的代码，心里瞬间一万匹草泥马奔腾而过。"文档呢？API接口文档呢？数据库说明呢？"然后开始各种找人问，微信群里@来@去，邮件发来发去，最后拿到的还是个过期版本...

简单说，ShowDoc就是一个非常适合IT团队的在线文档分享工具，它可以加快团队之间沟通的效率。不用下载安装任何软件，打开浏览器就能用，支持手机查看，团队协作也很方便。

最关键的是，它专门为程序员设计，知道你们的痛点在哪里。

https://appstore.lazycat.cloud/#/shop/detail/xyz.mxue.showdoc

上手指南：5分钟搞定第一个文档

应用安装后，打开语言界面，我们选右侧的中文

image.png

初始化成功后，会告诉你用户名密码

image.png

点击进入首页

image.png

登录系统

image.png

登录成功后，进入主页面

image.png

它内置了4种示例模版，可以参考用

image.png

点击"新建项目"，ShowDoc上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问，而私密项目则需要输入密码

image.png

选择建议：

  • 对外的API文档：选公开项目
  • 内部技术文档：选私密项目
  • 个人笔记整理：选私密项目

点击进入项目，开始写第一个文档，点击"新建页面"

image.png 输入页面标题（比如：用户登录接口）

image.png

点击编辑器上方的"API接口"按钮，插入模板

image.png

填写具体内容，比如：

**简要描述：** 
用户登录接口

**请求URL：** 
/api/user/login

**请求方式：**
POST 

**参数：** 

|参数名|必选|类型|说明|
|:----    |:---|:----- |-----   |
|username |是  |string |用户名   |
|password |是  |string |密码   |

**返回示例**
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

image.png 点击保存，完成！从项目主页可以看到

image.png

ShowDoc有历史版本功能，改错了随时可以恢复。而且可以看到谁在什么时候改了什么，团队协作必备。

image.png

权限管理很贴心

  • 项目所有者：可以删除项目、转让项目
  • 项目成员：可以编辑文档，但不能删除项目
  • 访客：只能查看，不能编辑

image.png

image.png

导出功能超实用

也可以将项目导出成word文件，以便离线浏览。老板要看文档？直接导出Word给他。需要离线查看？导出到本地随时看。

image.png

一份好的数据字典可以很方便地向别人说明你的数据库结构，如各个字段的释义等。 用"数据字典模板"，表名、字段名、类型、说明，一目了然 image.png

  • 可以直接从数据库导出结构，然后粘贴进去稍微调整就行

image.png

  • 新人入职看这个，比看代码效率高100倍

image.png

一些实际项目中的使用建议

按项目组织文档结构

项目名称/
├── API接口文档/
│   ├── 用户模块/
│   ├── 订单模块/
│   └── 支付模块/
├── 数据库文档/
│   ├── 用户表结构/
│   └── 订单表结构/
├── 部署文档/
└── 常见问题/

写文档时的小贴士

  1. 标题要清晰：让人一眼就知道这个接口是干什么的
  2. 参数说明要详细：必填/选填、数据类型、取值范围都要写清楚
  3. 返回示例要真实：直接复制真实的返回数据，别瞎编
  4. 错误码要全面：各种可能的错误情况都列出来

总结

ShowDoc就是一个让程序员写文档不再痛苦的工具。界面简洁，功能实用，免费够用，团队协作方便。

如果你的团队还在用Word写接口文档，还在微信群里传来传去找文档，真的该试试ShowDoc了。

作者
天天