《开发平台与服务技术实践专场-吴江-开发实践：使用Swagger快速打造REST API》.pdf

Swagger Implement Web API documents Jiang Wu 2015-10-17 Jiang Wu Swagger 2015-10-17 1 / 39 Context 1 Introduction 2 Swagger 3 Advanced topics 4 Summary Jiang Wu Swagger 2015-10-17 2 / 39 About me 8 years experience of Ruby on Rails Sinatra advocator, minimalism Gave a talk at RubyKaigi 2010 先讲两个笑话给⼤家提神 Jiang Wu Swagger 2015-10-17 3 / 39 程序员最痛恨两件事 写⽂档 别⼈不写⽂档 Programmers hate 2 things: writing documentation and no documentation. Jiang Wu Swagger 2015-10-17 4 / 39 I don’t always test my code… Jiang Wu Swagger 2015-10-17 5 / 39 Solution ’D’o not ’R’epeat ’Y’ourself Principle Jiang Wu Swagger 2015-10-17 6 / 39 Scenario (Nov. 2014) Web 2.0 application start from 2011 3 types of API consumers ▶ Native application (iOS/Android/PC/Mac) ▶ Third party service ▶ Javascript: single page application Jiang Wu Swagger 2015-10-17 7 / 39 Constraints 约束 HTTP/1.1 JSON data format (for JavaScript) REST architecture style Jiang Wu Swagger 2015-10-17 8 / 39 Separate 独⽴ Separate API from Web application. API specific Cookie Session Stateless Jiang Wu Swagger 2015-10-17 9 / 39 API documentations Must be important, clear and accurate. 重要 跨项⽬，跨公司 清楚 减少交流成本 正确 和代码保持同步 Jiang Wu Swagger 2015-10-17 10 / 39 Write by hand?