Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Build API with Swagger

Wu Jiang
October 12, 2015

Build API with Swagger

Wu Jiang

October 12, 2015
Tweet

Other Decks in Programming

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