开发平台与服务技术实践-开发实践使用Swagger快速打造RESTAPI文档.pptxVIP

Swagger Implement Web API documents Context 1 2 3 4 Introduction Swagger Advanced topics Summary Jiang Wu Swagger 2015-10-17 2 / 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? Huge effort Not up to date CSS? Jiang Wu Swagger 2015-10-17 11 / 39 Context 1 2 3 4 Introduction Swagger Advanced topics Summary Jiang Wu Swagger 2015-10-17 12 / 39 Demo /apidoc/ Jiang Wu Swagger 2015-10-17 13 / 39 Definitions Swagger Describe REST services Swagger UI Live testable documentation grape-swagger Generate API description Jiang Wu Swagger 2015-10-17 14 / 39 Problems solved by Swagger Communication between different teams/companies Synchronization of code and documentation. Test Verification of REST services Jiang Wu Swagger 2015-10-17 15 / 39 Describe REST services API routes Input types Output types Authorizations Jiang Wu Swagger 2015-10-17 16 / 39 API routes namespaces paths HTTP verbs documentations Jiang Wu Swagger 2015-10-17 17 / 39 Input types name type default value required/optional description Jiang Wu Swagger 2015-10-17 18 / 39 Benefit of input types Code Validation of parameters Documentation Description Validation of form