ShowDoc v3.0 发布 , 提升了产品颜值和操作体验，但是设计师说——

[star7th]

地址

开源地址： 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

相关截图

[star7th]

@pengtdyd

能的。其实 api 以及文档市场没有你想象中的小众。甚至说这个领域并不小众，只是说我占据的市场份额小。

[mydingyan]

@star7th
感谢，使用上述方法覆盖后重新升级正常。UI 变化挺大，体验下~

[yushiro]

嗯，在 ping.sx 上看了一下，这个域名+端口，国外访问国内全部 timeout ，只能国内访问。
公司出口正好是 hk 的……

[star7th]

@yushiro

额。那应该是我们的 ip 库定位有差异。如果是非中国的 ip ，我们会转向国外节点。你这样，你用个代理先临时访问，用大陆内或者美国代理都行，我们后面修正下对香港的 ip 库记录。

[Psily1017]

支持，刚毕业就接触到 showdoc ，从 1.0 用到了 3.0 ，肉眼可见的 ui 设计变得越来越漂亮和功能逻辑变得实用。

[star7th]

@Psily1017

1.0 的版本，那确实有好几年了。

[siknet]

模板风格开发方便吗？

[yushiro]

@star7th 我就是用了代理才发现可以访问，前几个月想用来着，结果发现 UI 全是乱的，我以为公司跑路了呢

[star7th]

@siknet 挺不方便的，因为 showdoc 看起来简单，但其实有很多很多细节。很多细节没有从一开始做成变量或者方便批量切换，所以要做在运行时换一套模板或者皮肤都不容易。而且我觉得嘛，模板不是刚需，可以暂时不用花精力。

[star7th]

@yushiro
我找了挺多香港 ip 来做测试，ip 库都显示正确。像你的那种情况，应该是因为 ip 被识别为大陆内地了——但实际网络是香港，所以才有这个问题。我估计应该是特例，因为我测试其他香港 ipi 都是正常的。
如果方便的话你可以把 ip 段告诉我下。或者你就针对 showdoc 使用代理访问吧。

[815979670]

问一下 showdoc 商业版的数据库也是 sqlite 吗？还是换了 MySQL 之类的？

[star7th]

@815979670

官网的并发，sqlite 肯定扛不住的。用了 mysql 和 redis 。

[star7th]

@815979670 实际上官网版跟开源版，很多数据库结构都不一样了。官网版我都是单独维护的。

[dcsite]

说实说，这个 UI 一如既往的难看…… 要是出个 GITBOOK 的主题就好了。

[star7th]

@dcsite
说实话，gitbook 当然不难看，但是如果将它封为效仿的标准，感觉就不是很有必要，因为是两种风格不一样的产品。
我推出 3.0 版后，除了你，没有一个人说难看的。最多就是说细节没到位，还可以完善，但远谈不上难看。

[u21t20o15]

希望可以做到自动化生成接口文档到私有部署的 showdoc ，然后 RunApi 能同步私有部署的 showdoc 接口数据进行本地化调试，提升开发效率。
目前在用 Apidoc 插件（注解生成接口文档）和 Yapi ，但是 yapi 不能保存调试的参数，每次都要重新写请求参数

[star7th]

@u21t20o15

RunApi 已经可以做到自动化生成接口文档到私有部署的 showdoc https://www.showdoc.com.cn/runapi

runapi 无法同步历史 showdoc 项目到客户端，因为历史上使用 markdown 编写，不是结构化数据，转不回来。但是从 runapi 创建的项目都可以自动生成文档到 showdoc

[star7th]

@u21t20o15

如果你要用注解生成 api 的话，可以参考这里
https://www.showdoc.com.cn/page/741656402509783

我推荐的做法是，注解生成 runapi 项目。而 runapi 项目会自动生产 showdoc 项目。从而实现你说的需求，即：
可以注释生成文档，并且生成的接口在 runapi 可以调试

[CaffreySun]

我也在用 ShowDoc ，我觉得问题不是出在 UI 难看上，而是排版和配色上，说白了就是没有 gitbook 可读性强，
gitbook 将大片显示区域留给内容，内容两侧有大片空白，目录位于最右侧，在看内容时视觉上没有干扰。
gitbook 整体字体更大更利于阅读。
gitbook 排版细节更好，
比如标题上边距大于下边距，从空间上就能知道这个标题是下面内容的标题
再比如段落之间的间距要大于段落内行间距，从空间上很容易区分段落。
还有就是配色问题，ShowDoc 整体配色颜色很多，显的有点凌乱

[geekboy]

希望可以加上评论功能