这是一个创建于 646 天前的主题，其中的信息可能已经有所发展或是发生改变。
地址
开源地址： https://github.com/star7th/showdoc
官网： https://www.showdoc.com.cn/
开发小故事
在年前，设计师基本为 showdoc 设计出了一套 ui 主题。然而直到昨天，我才按设计稿重构了一版 UI 。虽然外观看着变化也不算非常大，但实际上底层代码已重构掉了一半，很多产品逻辑导致的底层组件封装方式发生了变化，同时我也借此机会修复了历史上不少代码的遗留包袱。
到现在，完成度还没有很高，很多细节没打磨好，大约只达到设计稿原意的六七成。我决定直接先发布一个 3.0 版，后面的问题后面完善。
设计师说，我习惯一步到位，做完善了再上。
我跟他就这个观点进行了交流，还蛮有意思的。这是两种风格迥异的产品思维。一种是把产品打磨得很好，一出场就惊艳用户。一种是小步快走，分阶段迭代。实际上，我也看过设计师的其他作品，确实给人的第一感觉就很惊艳，其产品给目标用户的第一印象非常好。
对于我的项目而言，我要照顾到开发时间成本和宣发机会，我比较愿意追求留给用户一种 “这个产品一直在优化在进步”的印象，而不需花太长的时间“憋大招”来惊艳用户。
尽管这个观点不同，但是我非常欣赏设计师的产品思维和对细节的追求。后续也继续有意愿跟他合作其他产品。
3.0 版本更新了什么
重写了 UI 和交互逻辑，大大提升了视觉效果和操作体验，包括但不限于以下内容：
- 展示多个项目时候采用列表结构，同时完善项目分组功能，适合更多项目的场景
- 大部分打开新页面的操作，如用户中心、目录管理、团队管理等等，都改为当前页面弹窗的形式，方便关闭弹窗后无感回到之前的操作，避免割裂感。
- 完善拖放组件，涉及到拖放的场景，比如项目分组的拖放、页面排序的拖放、目录管理的拖放，都统一元素高度和样式。
- 调整项目展示页的布局，包括常规多页项目、单页项目和表格展示项目，增加统一的 header 和图标样式。
- 调整功能按钮的展示与收起逻辑，在便捷和简洁间取得平衡。
给新用户看的 showdoc 介绍
ShowDoc 是一个非常适合 IT 团队的在线 API 文档、技术文档工具，既有开箱即用的在线托管服务版，也有免费的开源版( github 1 万+ star )。通过 showdoc ，你可以方便地使用 markdown 语法来书写出美观的 API 文档、数据字典文档、技术文档、在线 excel 文档等等。如果不想编辑 markdown 文档，你还可以利用 showdoc 的自动化能力，从程序注释中自动生成 API 文档，或者从搭配的 RunApi 客户端（类似 postman 的 api 调试工具）中一边调试接口、一边自动生成文档。无需手动编写文档，释放生产力。通过分配项目成员和团队成员，你可以很方便地进行项目文档的权限管理和团队协作，也可以分享文档出去给朋友查看。ShowDoc 还支持多平台客户端，有 win 客户端、mac 客户端、ios 、android 等，更方便跨平台使用。目前超过 100000+的互联网团队正在使用 showdoc ，包括知名公司内部的一些团队，比如腾讯、华为、百度、京东、字节跳动等等。
关于 Showdoc 的详细介绍，请看： https://www.showdoc.com.cn/help
相关截图
 |
1
ieliwb 2023-02-14 11:12:32 +08:00
正在用，支持
|
 |
2
highf4324 2023-02-14 12:28:51 +08:00
很不错，不过还是建议首页左上角的 LOGO 不要用 PNG/JPEG 图像，因为看起来有点模糊。
建议直接用 svg ，这样无论怎样都不会模糊。 |
 |
3
yushiro 2023-02-14 12:30:32 +08:00 via iPhone
showdoc 是换域名了吗？用之前保存的 url 都没法正常显示了
|
 |
4
superliwei 2023-02-14 12:42:19 +08:00
👍 非常棒～！
|
 |
5
star7th OP @highf4324 主要是因为当初这个原始 logo 我没有保存源文件。只有一张大图。不过我倒可以使用大图生成各种分辨率的。所以你说的模糊问题，我尝试换个大分辨率一点的图标
|
|
6
star7th OP @yushiro showdoc 官网域名是 https://www.showdoc.com.cn/ ，我不清楚你以前是否使用了非官方平台（即别人搭建开源版给他自己用的，而你跑去注册账号了）
|
 |
7
akiyamamio 2023-02-14 13:04:13 +08:00
开源版和商业版有啥区别？
|
|
8
star7th OP |
|
9
star7th OP @akiyamamio 软件功能上的区别很小，可以忽略。
商业版主要是方便一些不想动手搭建的用户，更重要的是他们觉得数据交给 showdoc 官方去维护，比自己搭建的更可靠。尤其企业用户对数据的稳定性要求更高。如果是私自搭建开源版，服务器运维要你自己去保证可靠性。 |
|
10
yushiro 2023-02-14 13:42:43 +08:00 via iPhone
并不是用的其他人的，域名就是 showdoc.com.cn ，现在访问还是有问题，会去链接 dyfun-spare2.showdoc.这 com.cn:8888 这个地址，返回全部超时
|
 |
11
polarbearn 2023-02-14 14:00:47 +08:00
|
 |
12
EngAPI 2023-02-14 14:08:18 +08:00
用了你们推送半年多，感谢
|
 |
13
mydingyan 2023-02-14 14:28:14 +08:00
刚使用./showdoc update 命令升级了， 发现数据都被清空了， 应该怎么操作下
|
|
14
star7th OP @yushiro
dyfun-spare2.showdoc 是我们自建的 cdn 服务，你那边访问有问题吗？ 你是什么网络？如果是使用公司网络，会不会是公司安全限制了 8888 端口出口？能否用手机网络试一下？ |
|
17
star7th OP @mydingyan
可能是没有写入权限导致。在你目录 /showdoc_data 下应该能找到类似 html_bakxxxx 这样名字的文件夹。将它改掉，替换原来的 html 目录，然后重启下 docker 容器就好了 |
 |
18
lower 2023-02-14 15:00:42 +08:00
刚试了一下，8 年前的账号还能登录进去，当年的项目文档居然还都在😂
|
 |
19
pengtdyd 2023-02-14 15:02:19 +08:00
好奇，showdoc 开源项目商业化能赚到钱吗？本身就是很小众的产品
|
|
21
star7th OP |
|
23
yushiro 2023-02-14 16:34:48 +08:00 via iPhone
嗯，在 ping.sx 上看了一下，这个域名+端口，国外访问国内全部 timeout ，只能国内访问。
公司出口正好是 hk 的…… |
|
24
star7th OP |
 |
25
Psily1017 2023-02-14 17:12:22 +08:00
支持，刚毕业就接触到 showdoc ，从 1.0 用到了 3.0 ，肉眼可见的 ui 设计变得越来越漂亮和功能逻辑变得实用。
|
 |
27
siknet 2023-02-14 17:57:34 +08:00
模板风格开发方便吗？
|
|
28
yushiro 2023-02-14 18:13:52 +08:00 via iPhone
@star7th 我就是用了代理才发现可以访问，前几个月想用来着，结果发现 UI 全是乱的，我以为公司跑路了呢
|
|
29
star7th OP @siknet 挺不方便的，因为 showdoc 看起来简单，但其实有很多很多细节。很多细节没有从一开始做成变量或者方便批量切换，所以要做在运行时换一套模板或者皮肤都不容易。而且我觉得嘛，模板不是刚需，可以暂时不用花精力。
|
|
30
star7th OP @yushiro
我找了挺多香港 ip 来做测试，ip 库都显示正确。像你的那种情况，应该是因为 ip 被识别为大陆内地了——但实际网络是香港，所以才有这个问题。我估计应该是特例，因为我测试其他香港 ipi 都是正常的。 如果方便的话你可以把 ip 段告诉我下。或者你就针对 showdoc 使用代理访问吧。 |
 |
31
815979670 2023-02-14 20:33:15 +08:00
问一下 showdoc 商业版的数据库也是 sqlite 吗？还是换了 MySQL 之类的？
|
 |
34
dcsite 2023-02-15 09:16:37 +08:00
说实说，这个 UI 一如既往的难看…… 要是出个 GITBOOK 的主题就好了。
|
|
35
star7th OP @dcsite
说实话，gitbook 当然不难看，但是如果将它封为效仿的标准，感觉就不是很有必要，因为是两种风格不一样的产品。 我推出 3.0 版后，除了你，没有一个人说难看的。最多就是说细节没到位，还可以完善，但远谈不上难看。 |
 |
36
u21t20o15 2023-02-15 09:46:41 +08:00
希望可以做到自动化生成接口文档到私有部署的 showdoc ，然后 RunApi 能同步私有部署的 showdoc 接口数据进行本地化调试，提升开发效率。
目前在用 Apidoc 插件（注解生成接口文档）和 Yapi ，但是 yapi 不能保存调试的参数，每次都要重新写请求参数 |
|
37
star7th OP @u21t20o15
RunApi 已经可以做到自动化生成接口文档到私有部署的 showdoc https://www.showdoc.com.cn/runapi runapi 无法同步历史 showdoc 项目到客户端，因为历史上使用 markdown 编写，不是结构化数据，转不回来。但是从 runapi 创建的项目都可以自动生成文档到 showdoc |
|
38
star7th OP @u21t20o15
如果你要用注解生成 api 的话，可以参考这里 https://www.showdoc.com.cn/page/741656402509783 我推荐的做法是，注解生成 runapi 项目。而 runapi 项目会自动生产 showdoc 项目。从而实现你说的需求，即： 可以注释生成文档，并且生成的接口在 runapi 可以调试 |
 |
39
CaffreySun 2023-02-15 09:59:03 +08:00
我也在用 ShowDoc ，我觉得问题不是出在 UI 难看上，而是排版和配色上，说白了就是没有 gitbook 可读性强，
gitbook 将大片显示区域留给内容，内容两侧有大片空白，目录位于最右侧，在看内容时视觉上没有干扰。 gitbook 整体字体更大更利于阅读。 gitbook 排版细节更好， 比如标题上边距大于下边距，从空间上就能知道这个标题是下面内容的标题 再比如段落之间的间距要大于段落内行间距，从空间上很容易区分段落。 还有就是配色问题，ShowDoc 整体配色颜色很多，显的有点凌乱 |
 |
40
geekboy 2023-02-15 10:03:39 +08:00
希望可以加上评论功能
|
|
41
star7th OP @CaffreySun
showdoc 没办法像 gitbook 那种将大片显示区域留给内容，因为两者面向的文档类型不一样。 像 gitbook 这样的大片区域，非常适合文字段落饱满的情况，比如写一篇教程，文字或者代码非常饱满，可以充满一个个段落的。 但是 showdoc 没办法，因为 showdoc 大部分用来解决 api 文档场景。写 api 文档，段落是不饱满的，我自己测试过，在锻炼不饱满的情况下，不同分辨率下的视觉效果无法统一，且都不算好看。 至于说排版细节，那就确实是的，showdoc 有不少要改进的地方。但无论如何，都不能直接仿照 gitbook ，因为主要面向的文档类型不一样。 至于说配色的问题，我后面会咨询设计师意见，后面再做个更完善的版本。 |
|
42
star7th OP @geekboy
评论需求是一个很模糊的需求。说需要嘛，这几年来用户的呼声不大。说不需要嘛，偶尔会有人说。https://github.com/star7th/showdoc/issues/553 我自己依然没想好。再确认之前，我可能暂时先不动手做这个，因为评论功能会强势地占用视觉空间，并不是躲在一个二级菜单里等着用户使用就好。 |
 |
43
sairoa 2023-02-15 12:08:22 +08:00
代码块输入英文单引号会被转义，保存后页面显示为`'`。
|
 |
45
gongquanlin 2023-02-15 21:24:23 +08:00  1
用了好几年了，一直在用。牛逼，加油。什么时候能优化一下移动端就牛逼了，现在在手机上用 app 会有很多错位 /占满的问题
|
|
46
star7th OP |
 |
47
idragonet 2023-02-18 20:25:02 +08:00
3.0 怎么编辑框，有时候 ctrl+c 容易导致编辑框消失？
|
|
48
star7th OP |
Select Language