{"action":"opened","issue":{"url":"https://api.github.com/repos/xizhibei/blog/issues/18","repository_url":"https://api.github.com/repos/xizhibei/blog","labels_url":"https://api.github.com/repos/xizhibei/blog/issues/18/labels{/name}","comments_url":"https://api.github.com/repos/xizhibei/blog/issues/18/comments","events_url":"https://api.github.com/repos/xizhibei/blog/issues/18/events","html_url":"https://github.com/xizhibei/blog/issues/18","id":158059561,"number":18,"title":"关于API文档","user":{"login":"xizhibei","id":866629,"avatar_url":"https://avatars.githubusercontent.com/u/866629?v=3","gravatar_id":"","url":"https://api.github.com/users/xizhibei","html_url":"https://github.com/xizhibei","followers_url":"https://api.github.com/users/xizhibei/followers","following_url":"https://api.github.com/users/xizhibei/following{/other_user}","gists_url":"https://api.github.com/users/xizhibei/gists{/gist_id}","starred_url":"https://api.github.com/users/xizhibei/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/xizhibei/subscriptions","organizations_url":"https://api.github.com/users/xizhibei/orgs","repos_url":"https://api.github.com/users/xizhibei/repos","events_url":"https://api.github.com/users/xizhibei/events{/privacy}","received_events_url":"https://api.github.com/users/xizhibei/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2016-06-02T04:58:18Z","updated_at":"2016-06-02T04:58:18Z","closed_at":null,"body":"先从一次面试经历说起，记得有次面试，我问被面试者一个API文档的问题，\r\n\r\n>『用gitbook。』\r\n>  我呆了一下\r\n>『那如果你们修改了API接口，怎么修改文档呢?』\r\n>『我们文档也用git管理，直接修改提交。』\r\n>『那你们有没有遇到某次代码修改之后，忘记修改文档了?』\r\n> 『……』\r\n\r\n我想在实际开发中，这样的做法很容易顾此失彼，忘记更新代码，造成了文档与代码不一致的情况。\r\n\r\n众所周知，好的文档能提高使用这个项目的工程师的开发效率，相信你也遇到过这样的情况，某个开源项目，照着文档实现后发现结果不理想，甚至无法运行的情况，然后只能去看代码。（其实从另一个角度说，这也能逼着使用者去看代码，理解原理。。。）\r\n\r\n只是，在同一个项目里的时候，APP工程师不用去看服务器工程师实现的代码吧？于是一份好的文档能省不少事，提高各自的开发效率。如果你遇到过，Android跟iOS开发工程师分别来问你API接口的情况，你就很能理解了。\r\n\r\n一个我认为理想中的跟APP工程师协同开发流程是：先跟所有人，包括产品经理一起看文档，弄清需求，分拆任务，约定好接口，参数之类的。然后服务器工程师按照约定写一个mock API提供给APP工程师，之后两边各自开发测试，直到最后联调通过。\r\n\r\n其中约定好的API接口，由于在开发过程中可能会改，于是，一个可以动态更新的API文档就很重要。有这么几个选择：\r\n* apidoc.js\r\n* Evernote之类的笔记共享\r\n* gitbook\r\n\r\n很明显，我认为将文档跟代码放在一起是最好的选择（没错，我就是来安利apidoc.js的 😆 ），代码一改，直接在代码上面的文档修改，然后在测试环境部署时，加个pre-update生成新文档即可，通知APP工程师即可。\r\n\r\n这样的话，可以避免一定的文档与代码不一致的情况。（当然，如果服务器工程师懒的写文档的话，那也谁也救不了。"}}
{"actor":{"display_login":"xizhibei"}}