API文档、技术文档工具--showdoc

ShowDoc是什么

ShowDoc是一个非常适合IT团队的在线API文档、技术文档工具。
通过showdoc，你可以方便地使用markdown语法来书写出美观的API文档、数据字典文档、技术文档、在线excel文档等等。
如果不想编辑markdown文档，你还可以利用showdoc的自动化能力，从程序注释中自动生成API文档，或者从搭配的RunApi客户端（类似postman的api调试工具）中一边调试接口、一边自动生成文档。
通过分配项目成员和团队成员，你可以很方便地进行项目文档的权限管理和团队协作，也可以分享文档出去给朋友查看。
ShowDoc还支持多平台客户端，有win客户端、mac客户端、ios、android等，更方便跨平台使用。
目前超过100000+的互联网团队正在使用showdoc，包括知名公司内部的一些团队，比如腾讯、华为、百度、京东、字节跳动、顺丰等等。

它可以用来做什么

  • API文档
    随着移动互联网的发展，BaaS（后端即服务）越来越流行。
    服务端提供API，APP端或者网页前端便可方便调用数据。
    用ShowDoc可以非常方便快速地编写出美观的API文档。

  • 数据字典
    一份好的数据字典可以很方便地向别人说明你的数据库结构，如各个字段的释义等。

  • 说明文档
    你完全可以使用showdoc来编写一些工具的说明书,也可以编写一些技术规范说明文档以供团队查阅

它都有些什么功能

  • 分享与导出
    响应式网页设计，可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件，以便离线浏览。

  • 权限管理

    • 公开项目与私密项目
      ShowDoc上的项目有公开项目和私密项目两种。
      公开项目可供任何登录与非登录的用户访问，而私密项目则需要输入密码验证访问。
      密码由项目创建者设置
    • 项目转让
      项目创建者可以自由地把项目转让给网站的其他用户。
    • 项目成员
      你可以很方便地为ShowDoc的项目添加、删除项目成员。项目成员可以对项目进行编辑，但不可转让或删除项目（只有项目创建者才有权限）
    • 团队管理
      利用showdoc的团队功能你可以更好地进行团队协作

  • 编辑功能

    • markdown编辑
      ShowDoc采用markdown编辑器，无论是编辑还是阅读体验都极佳很棒。如果你不了解Markdown，请在搜索引擎搜索”认识与入门 Markdown”
    • 模板插入
      在ShowDoc的编辑页面，点击编辑器上方的按钮可方便地插入API接口模板和数据字典模板。插入模板后，剩下的就是改动数据了，省去了很多编辑的力气。
    • 历史版本
      ShowDoc为页面提供历史版本功能，你可以方便地把页面恢复到之前的版本。

  • 多平台
    showdoc支持网页版、手机app版和电脑客户端版。客户端

  • 自动化

    • 可从代码注释中自动生成文档
    • 搭配的RunApi客户端，可调试接口和自动生成文档

官网





本地部署

使用docker部署

参考文档 https://www.showdoc.com.cn/help/65610

镜像

# 原版官方镜像安装命令(中国大陆用户不建议直接使用原版镜像，可以用后面的加速镜像)
# 如果你打算安装ARM版本的docker镜像，请将 latest 标签改为 arm-latest。如果失败，可尝试根据自身设备架构，加入--platform参数
docker pull star7th/showdoc:latest 

# 中国大陆镜像安装命令（安装后记得执行docker tag命令以进行重命名）
docker pull registry.cn-shenzhen.aliyuncs.com/star7th/showdoc
docker tag registry.cn-shenzhen.aliyuncs.com/star7th/showdoc:latest star7th/showdoc:latest

准备

准备文件夹

#新建存放showdoc数据的目录
mkdir -p /showdoc_data/html
chmod  -R 777 /showdoc_data

准备资源清单文件

services:
  showdoc:
    container_name: showdoc
    image: registry.cn-shenzhen.aliyuncs.com/star7th/showdoc
    restart: always
    user: '0'
    privileged: true
    ports:
      - 4999:80
    volumes:
      - ./showdoc_data/html:/var/www/html/

部署

docker compose up -d

访问

http://<IP>:4999

用户名密码：showdoc/123456

登录后你便可以看到右上方的管理后台入口。建议登录后修改密码。

RunApi

介绍

runapi是一个以接口为核心的开发测试工具（功能上类似postman）, 包含接口测试/自动流程测试/Mock数据/项目协作等功能。

它和showdoc相辅相成：showdoc以文档为核心，侧重文档编写和知识资料沉淀。
而runapi则以接口为核心，包含接口测试、管理、Mock数据、自动化流程测试等一系列功能。
同时它将自动生成文档到showdoc，无须再手动编写文档，释放生产力；
共用showdoc的团队管理机制，很好地实现接口的自动化和多人协作。
相信使用 showdoc + runapi 这两个工具组合，能够极大地提高IT团队的效率。

客户端下载

登录

客户端登录的时候可以选择是官方提供的托管服务器、还是自己私有的服务器

官网托管

私有化部署的

预览



数据说明

runapi的数据可以生成markdown格式，但不可逆，markdown数据很难再转换回来runapi。
所以它无法跟showdoc原有数据互相转换。
只是它们可以共用文档浏览/团队协作等功能。
同时runapi生成的文档只能在runapi上编辑，不能在showdoc上编辑。

在线精简版

在线精简版和客户端版差别很大，它只包含简单的接口请求以及生成markdown代码，只用作简单调试，无法自动生成文档到showdoc以及无法使用项目团队协作功能等。
访问地址： http://runapi.showdoc.cc

问题

忘记了密码怎么办？

如果是使用在线ShowDoc，忘记密码的话可联系xing7th@gmail.com，邮件中说明你的用户名和旗下项目名字（至少提供两个项目）。
如果是自己部署的ShowDoc，则首先根据前面安装文档进行升级，确保使用最新代码(划重点）。
然后，根据安装方式的不同有不同的密码重置方式。
如果是使用官方脚本或者docker方式安装的，请在命令行执行命令：

docker exec showdoc bash -c  "cd /var/www/html/ && php ./index.php home/common/repasswd"

如果是手动安装php方式的，则在命令行中切换到showdoc安装目录然后执行：

php index.php home/common/repasswd

以上命令会把管理员showdoc的密码重置为123456 。用此密码登录管理后台即可管理普通用户以及项目。建议登录后修改密码。

使用总结

优点：

  1. 可以完全没功能限制的私有化部署
  2. 功能实用，机会没有用户上的功能
  3. 界面简单明了
  4. 上手容易
  5. 部署方便，更新方便，文档齐全
  6. 可测试api并且自动生成api文档
  7. 分享文档非常方便安全
  8. 可以写markdown文档
  9. 开源免费

不足：
暂未发现，非常好用

posted @ 2025-01-08 15:13  厚礼蝎  阅读(2236)  评论(0)    收藏  举报