操作小tips——API文档的修改与备份

<h3>修改</h3> <p>可在项目的根目录新建一个名为“修改记录”的页面。里面新建一张表格。一行记录代表一个修改记录，如：</p> <ul> <li>2022年5月</li> </ul> <table> <thead> <tr> <th>日期</th> <th>修改人</th> <th>涉及接口</th> <th>修改内容</th> </tr> </thead> <tbody> <tr> <td>5月21日</td> <td>张三</td> <td>用户相关-用户登录</td> <td>新增参数校验</td> </tr> <tr> <td>5月21日</td> <td>张三</td> <td>用户相关-用户登录</td> <td>新增参数校验</td> </tr> <tr> <td>5月21日</td> <td>张三</td> <td>用户相关-用户登录</td> <td>新增参数校验</td> </tr> </tbody> </table> <p>如果修改记录较多，可以考虑按照月份归类，如5月份的修改整理为一张表格，4月份的修改整理为一张表格。但这几个表格都放在同一个页面即可。</p> <p>一个项目示例：<a href="https://www.showdoc.cc/demo?page_id=14980701">https://www.showdoc.cc/demo?page_id=14980701</a></p> <p>showdoc考虑过从程序层面记录下用户对每个页面的操作，然后生成记录。但发现这样其实效果有限。因为：</p> <p>1、如果程序事无巨细记录下用户对每个页面的操作，则可能会产生大量无关紧要的记录（比如一个页面为了预览效果可能修改了很多次，但这么多次每次都记录下来是没必要的）。</p> <p>2、程序记录的话比较难知道你更新的内容（例如它怎么知道我只是改了返回结果的格式呢？）。</p> <p>基于以上，最好修改记录最好专门存放在一个页面，由人工来维护。只记录那些有必要让其他合作伙伴知悉的接口变更。</p> <h3>备份</h3> <p>一般情况下，showdoc提供单页面的历史版本功能。在编辑该版本时、在编辑上方便可以看到历史版本的入口。你可以选择恢复某个页面的历史版本。</p> <p>在涉及多页面、多修改情况下，项目管理员可以考虑将项目复制备份。具体操作是，回到项目主页，点击新建项目，勾选“复制已存在项目。</p> <p>对showdoc任何疑问和建议可反馈至xing7th@gmail.com</p>