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