Build API with Swagger

Transcript

1. Swagger Implement Web API documents Jiang Wu 2015-10-11 Jiang Wu Swagger 2015-10-11 1 / 49
2. Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang Wu Swagger 2015-10-11 2 / 49
3. Do you remember this? Jiang Wu Swagger 2015-10-11 3 / 49
4. 本尊在此 It’s me! Jiang Wu Swagger 2015-10-11 4 / 49
5. Oops!…I did it again Figure: RubyConf Taiwan 2015 Jiang Wu Swagger 2015-10-11 5 / 49
6. Presentation Tools Rabbit ▶ Written in Ruby ▶ Matz uses this ▶ Has time control Please allow me off topic one more page… Jiang Wu Swagger 2015-10-11 6 / 49
7. Code of Conduct Ruby China played well against sexism. RubyConf China should have conference code of conduct. Bundler now creates contributor code of conduct for you. Jiang Wu Swagger 2015-10-11 7 / 49
8. Scenario Rails application 3 types of API consumers ▶ Native application (iOS/Android/PC/Mac) ▶ Third party service ▶ JavaScript: single page application Jiang Wu Swagger 2015-10-11 8 / 49
9. Constraints HTTP/1.1 JSON data format REST architecture style Jiang Wu Swagger 2015-10-11 9 / 49
10. Ruby Libraries grape REST services doorkeeper OAuth provider Thanks yorkxin’s blog for the help. Will try wine bouncer next time(thanks sinalpha). Jiang Wu Swagger 2015-10-11 10 / 49
11. Components Rails + doorkeeper OAuth admin page OAuth grant flow Grape + doorkeeper Handle OAuth token Jiang Wu Swagger 2015-10-11 11 / 49
12. API documentations Must be significant, clear and accurate. 重要 跨项⽬组，跨公司 清楚 减少交流成本 正确 和代码保持同步 Jiang Wu Swagger 2015-10-11 12 / 49
13. 程序员最痛恨两件事 写⽂档 别⼈不写⽂档 Coders hate 2 things: writing documentation and no documentation. Solution ’D’o not ’R’epeat ’Y’ourself Priciple Jiang Wu Swagger 2015-10-11 13 / 49
14. Remove duplication documentation -> code WSDL code -> documentation RDoc, YARD, Rocco(annotated source code) literate programming noweb, Org Mode, Literate Haskell Jiang Wu Swagger 2015-10-11 14 / 49
15. REST API specifications Swagger RAML Blueprint Jiang Wu Swagger 2015-10-11 15 / 49
16. Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang Wu Swagger 2015-10-11 16 / 49
17. Demo https://api.gitcafe.com/apidoc/ Jiang Wu Swagger 2015-10-11 17 / 49
18. Definitions Swagger Describe REST services Swagger UI Live testable documentation grape-swagger Generate API description Jiang Wu Swagger 2015-10-11 18 / 49
19. Describe REST services API routes Input types Output types Authorizations Jiang Wu Swagger 2015-10-11 19 / 49
20. Implementation 1 Grape basic declaration 2 Namespace and routes 3 ’params’ -> input type 4 Grape::Entity -> output type 5 Swagger information Jiang Wu Swagger 2015-10-11 20 / 49
21. Grape basic declaration class API < Grape::API # API routes prefix prefix 'api' # API version version 'v1', using: :path # load other API mount Endpoints end Jiang Wu Swagger 2015-10-11 21 / 49
22. namespaces namespace "projects" do mount ProjectsAPI # could be variable value # and cascadable namespace ":identity" do mount SingleProjectAPI end end Jiang Wu Swagger 2015-10-11 22 / 49
23. API routes Sinatra like DSL, declared with HTTP methods. desc "Show single project" # get|post|put|patch|delete get "/:project" do # Your implementation end Jiang Wu Swagger 2015-10-11 23 / 49
24. Input types params do requires :name, type: String optional :public, type: Boolean, default: false end Jiang Wu Swagger 2015-10-11 24 / 49
25. Validation of input types Validate requests and return 400 status code for typecast error or missing value. Jiang Wu Swagger 2015-10-11 25 / 49
26. Output types class Project < Grape::Entity # Output fields expose :name, documentation: { type: 'string', desc: 'Project name' } end Jiang Wu Swagger 2015-10-11 26 / 49
27. Refer to other types class Project < Grape::Entity expose :owner, # with 'using' using: Account, documentation: { type: 'Account' } end Jiang Wu Swagger 2015-10-11 27 / 49
28. Swagger information (1) Delare with add_swagger_documentation api_version mount_path authorizations info Jiang Wu Swagger 2015-10-11 28 / 49
29. Swagger informations (2) Add documentaions of namespace params output types (options of ’desc’) OAuth scopes (options of ’desc’) API codes (options of ’get’/’post’) Jiang Wu Swagger 2015-10-11 29 / 49
30. Live Test Similiar as doctest of Python """ input and output, REPL way >>> factorial(5) 120 """ def factorial(n): Documentation is both sample and test. Jiang Wu Swagger 2015-10-11 30 / 49
31. API test before Swagger Write it by yourself Browser plugins (not quite works) RestClient Firefox + Chrome Proprietary softwares Postman Chrome + NodeJS Paw Mac Jiang Wu Swagger 2015-10-11 31 / 49
32. Short summary of Swagger API routes Input types Output types Authorizations Jiang Wu Swagger 2015-10-11 32 / 49
33. Swagger clients REST clients, not Swagger specific. Generate with swagger-codegen, supports Android and iOS. Dynamic code generation in JavaScript/Ruby/Python. Jiang Wu Swagger 2015-10-11 33 / 49
34. WebView or not? 1st edition, use WebView 2nd edition, native view 3rd edition, WebView (Electron) Jiang Wu Swagger 2015-10-11 34 / 49
35. Pitfall Grape supports wildcard(*) path, while live documentation doesn’t, and we found out bug was in grape-swagger. Jiang Wu Swagger 2015-10-11 35 / 49
36. Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang Wu Swagger 2015-10-11 36 / 49
37. Unleash power of database API Database Routes Tables/Views Input types Constraints, Types Output types Table columns Authorizations Roles Jiang Wu Swagger 2015-10-11 37 / 49
38. Design philosophy Can we use the declarative information in a relational db schema to mechanically generate an HTTP API? begriffs Jiang Wu Swagger 2015-10-11 38 / 49
39. Features of PostgreSQL Data types Array, HStore, GIS, JSONB(since 9.4) Procedure languages PL/pgSQL, PL/Python, PL/V8 Message queue NOTIFY/LISTEN Full text search tsvector/tsquery Jiang Wu Swagger 2015-10-11 39 / 49
40. Schema -> API Schema path -> API version Tables/views -> API routes Where clause -> query params GET /projects?age=lt.P7D&public=eq.true Query projects created in 7 days and public. Jiang Wu Swagger 2015-10-11 40 / 49
41. Pagination -> Range headers GET /items HTTP/1.1 Range-Unit: items Range: 0-24 HTTP/1.1 206 Partial Content Accept-Ranges: items Content-Range: 0-24/100 Range-Unit: items Jiang Wu Swagger 2015-10-11 41 / 49
42. DML -> HTTP methods insert POST update PATCH upsert/merge PUT delete DELETE Jiang Wu Swagger 2015-10-11 42 / 49
43. DB Roles -> Authorizations Need extra work to support normal database-based authentication and authorizations. Jiang Wu Swagger 2015-10-11 43 / 49
44. Why PostgREST? Counter attack to NoSQL Bare metal speed (written in Haskell) HTTP protocol Jiang Wu Swagger 2015-10-11 44 / 49
45. Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang Wu Swagger 2015-10-11 45 / 49
46. Swagger Describe REST services. Provide Live testable documentation with Swagger UI. Can generate with grape-swagger. Disadvantage: have to investigate across components when debugging. Jiang Wu Swagger 2015-10-11 46 / 49
47. PostgREST DB Schema -> API Rediscover values of RDBMS Advantage: can utilize mature tools built around RDBMS, like graphivz Jiang Wu Swagger 2015-10-11 47 / 49
48. Apply DRY principle Abstract instead of duplicate Select proper tools Bring values Jiang Wu Swagger 2015-10-11 48 / 49
49. Q&A Questions? Twitter: @masterwujiang Github: @nouse Linkedin: @nouse Jiang Wu Swagger 2015-10-11 49 / 49