Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Swagger
Implement Web API documents
Jiang Wu
2015-09-12
Jiang Wu Swagger 2015-09-12 1 / 42
Context
1 Introduction
2 Swagger
3 PostgREST
4 Summary
Jiang Wu Swagger 2015-09-12 2 / 42
Do you remember this?
Jiang Wu Swagger 2015-09-12 3 / 42
本尊在此 It’s me!
Jiang Wu Swagger 2015-09-12 4 / 42
Scenario 場景
Why we adopted Swagger?
Rails application
3 types of API consumers
▶ Native application
(iOS/Android/PC/Mac)
▶...
Constraints 約束
HTTP/1.1
JSON data format
REST architecture style
Jiang Wu Swagger 2015-09-12 6 / 42
Ruby Gems
grape REST services
doorkeeper OAuth provider
Thanks yorkxin’s blog for the help.
Jiang Wu Swagger 2015-09-12 7 ...
API documentations
Must be important, clear and accurate.
重要 跨專案組,跨公司
清楚 減少交流成本
正確 和程式碼保持同步
Jiang Wu Swagger 2015-09-12 8 ...
程式設計師痛恨兩件事情
寫⽂檔
別⼈不寫⽂檔
Coders hate 2 things: writing
documentation and no documentation.
Solution
’D’o not ’R’epeat ’Y’our...
Remove duplication
documentation -> code WSDL
code -> documentation RDoc, YARD,
Rocco(annotated source code)
literate prog...
Context
1 Introduction
2 Swagger
3 PostgREST
4 Summary
Jiang Wu Swagger 2015-09-12 11 / 42
Demo
https://api.gitcafe.com/apidoc/
Jiang Wu Swagger 2015-09-12 12 / 42
Definitions
Swagger
Describe REST services
Swagger UI
Live testable documentation
grape-swagger
Generate API description
J...
Describe REST services
API routes
Input types
Output types
Authorizations
Jiang Wu Swagger 2015-09-12 14 / 42
Implementation 實作
1 Grape basic declaration
2 Namespace and routes
3 ’params’ -> input type
4 Grape::Entity -> output type...
Grape basic declaration
class API < Grape::API
# API routes prefix
prefix 'api'
# API version
version 'v1', using: :path
#...
namespaces 命名空間
namespace "projects" do
mount ProjectsAPI
# namepsaces can be variable
# and cascadable
namespace ":identi...
API routes
Sinatra like DSL, declared with HTTP
methods.
desc "Show single project"
# get|post|put|patch|delete
get "/:pro...
Input types 輸⼊類型
params do
requires :name, type: String
optional :public,
type: Boolean,
default: false
end
Validate reque...
Output types 輸出類型
class Project < Grape::Entity
# Output fields
expose :name,
documentation: {
type: 'string',
desc: 'Proj...
Refer to other types
class Project < Grape::Entity
expose :owner,
# with 'using'
using: Account,
documentation: {
type: 'A...
OAuth authorizations
Rails + doorkeeper
OAuth admin page
OAuth grant flow
Grape + doorkeeper
Handle OAuth token
Jiang Wu S...
Swagger information (1)
Delare with
add_swagger_documentation
api_version
mount_path
authorizations
info
Jiang Wu Swagger ...
Swagger informations (2)
Add documentaions of
namespace
params
output types (options of ’desc’)
OAuth scopes (options of ’...
Live Test
Similiar as doctest of Python
""" input and output, REPL way
>>> factorial(5)
120
"""
def factorial(n):
Document...
API test before Swagger
Write it by yourself
Browser plugins (not quite works)
RestClient Firefox + Chrome
Proprietary sof...
Short summary of Swagger
API routes
Input types
Output types
Authorizations
Jiang Wu Swagger 2015-09-12 27 / 42
Ruby Swagger clients
REST clients are not Swagger specific
I started my work 3 days ago
Will be available soon
Virtus gem ...
Unleash power of database
API Database
Routes Tables/Views
Input types Constraints, Types
Output types Table columns
Autho...
Context
1 Introduction
2 Swagger
3 PostgREST
4 Summary
Jiang Wu Swagger 2015-09-12 30 / 42
Design philisophy
Can we use the declarative
information in a relational db
schema to mechanically generate
an HTTP API?
b...
Features of PostgreSQL
Data types Array, HStore, GIS,
JSONB(since 9.4)
Procedure languages PL/pgSQL,
PL/Python, PL/V8
Mess...
Schema -> API
Schema path -> API version
Tables/views -> API routes
Where clause -> query params
GET
/projects?age=lt.P7D&...
Pagination -> Range headers
GET /items HTTP/1.1
Range-Unit: items
Range: 0-24
HTTP/1.1 206 Partial Content
Accept-Ranges: ...
DML -> HTTP methods
insert POST
update PATCH
upsert/merge PUT
delete DELETE
Jiang Wu Swagger 2015-09-12 35 / 42
DB Roles -> Authorizations
Need extra works to support normal
database-based authentication and
authorizations.
Jiang Wu S...
Why PostgREST?
Counter attack to NoSQL
Bare metal speed (written in Haskell)
HTTP protocol
Jiang Wu Swagger 2015-09-12 37 ...
Context
1 Introduction
2 Swagger
3 PostgREST
4 Summary
Jiang Wu Swagger 2015-09-12 38 / 42
Swagger
Describe REST services
Provide Live testable documentation
with Swagger UI
Can generate with grape-swagger
Disadva...
PostgREST
DB Schema -> API
Rediscover values of RDBMS
Advantage: can utilize more mature
tools built around RDBMS
Jiang Wu...
Apply DRY principle
Abstract not duplicate
Select proper tools
Bring values
Jiang Wu Swagger 2015-09-12 41 / 42
Q&A
Questions?
Twitter: @masterwujiang
Github: @nouse
Linkedin: @nouse
Jiang Wu Swagger 2015-09-12 42 / 42
Upcoming SlideShare
Loading in …5
×

Implement Web API with Swagger

2,043 views

Published on

Swagger is a description standard of REST API. I will show you features of Swagger UI, and how to make it out with grape and grape-swagger. At the end introduces PostgREST and emphasizes DRY principle.

Published in: Software
  • Be the first to comment

Implement Web API with Swagger

  1. 1. Swagger Implement Web API documents Jiang Wu 2015-09-12 Jiang Wu Swagger 2015-09-12 1 / 42
  2. 2. Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang Wu Swagger 2015-09-12 2 / 42
  3. 3. Do you remember this? Jiang Wu Swagger 2015-09-12 3 / 42
  4. 4. 本尊在此 It’s me! Jiang Wu Swagger 2015-09-12 4 / 42
  5. 5. Scenario 場景 Why we adopted Swagger? Rails application 3 types of API consumers ▶ Native application (iOS/Android/PC/Mac) ▶ Third party service ▶ Javascript: single page application Jiang Wu Swagger 2015-09-12 5 / 42
  6. 6. Constraints 約束 HTTP/1.1 JSON data format REST architecture style Jiang Wu Swagger 2015-09-12 6 / 42
  7. 7. Ruby Gems grape REST services doorkeeper OAuth provider Thanks yorkxin’s blog for the help. Jiang Wu Swagger 2015-09-12 7 / 42
  8. 8. API documentations Must be important, clear and accurate. 重要 跨專案組,跨公司 清楚 減少交流成本 正確 和程式碼保持同步 Jiang Wu Swagger 2015-09-12 8 / 42
  9. 9. 程式設計師痛恨兩件事情 寫⽂檔 別⼈不寫⽂檔 Coders hate 2 things: writing documentation and no documentation. Solution ’D’o not ’R’epeat ’Y’ourself Priciple Jiang Wu Swagger 2015-09-12 9 / 42
  10. 10. Remove duplication documentation -> code WSDL code -> documentation RDoc, YARD, Rocco(annotated source code) literate programming noweb, Org Mode, Literate Haskell Jiang Wu Swagger 2015-09-12 10 / 42
  11. 11. Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang Wu Swagger 2015-09-12 11 / 42
  12. 12. Demo https://api.gitcafe.com/apidoc/ Jiang Wu Swagger 2015-09-12 12 / 42
  13. 13. Definitions Swagger Describe REST services Swagger UI Live testable documentation grape-swagger Generate API description Jiang Wu Swagger 2015-09-12 13 / 42
  14. 14. Describe REST services API routes Input types Output types Authorizations Jiang Wu Swagger 2015-09-12 14 / 42
  15. 15. Implementation 實作 1 Grape basic declaration 2 Namespace and routes 3 ’params’ -> input type 4 Grape::Entity -> output type 5 Doorkeeper -> OAuth authorizations 6 Swagger information Jiang Wu Swagger 2015-09-12 15 / 42
  16. 16. 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-09-12 16 / 42
  17. 17. namespaces 命名空間 namespace "projects" do mount ProjectsAPI # namepsaces can be variable # and cascadable namespace ":identity" do mount SingleProjectAPI end end Jiang Wu Swagger 2015-09-12 17 / 42
  18. 18. 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-09-12 18 / 42
  19. 19. Input types 輸⼊類型 params do requires :name, type: String optional :public, type: Boolean, default: false end Validate requests and return 400 status code for typecast error or missing value. Jiang Wu Swagger 2015-09-12 19 / 42
  20. 20. Output types 輸出類型 class Project < Grape::Entity # Output fields expose :name, documentation: { type: 'string', desc: 'Project name' } end Jiang Wu Swagger 2015-09-12 20 / 42
  21. 21. Refer to other types class Project < Grape::Entity expose :owner, # with 'using' using: Account, documentation: { type: 'Account' } end Jiang Wu Swagger 2015-09-12 21 / 42
  22. 22. OAuth authorizations Rails + doorkeeper OAuth admin page OAuth grant flow Grape + doorkeeper Handle OAuth token Jiang Wu Swagger 2015-09-12 22 / 42
  23. 23. Swagger information (1) Delare with add_swagger_documentation api_version mount_path authorizations info Jiang Wu Swagger 2015-09-12 23 / 42
  24. 24. 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-09-12 24 / 42
  25. 25. 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-09-12 25 / 42
  26. 26. 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-09-12 26 / 42
  27. 27. Short summary of Swagger API routes Input types Output types Authorizations Jiang Wu Swagger 2015-09-12 27 / 42
  28. 28. Ruby Swagger clients REST clients are not Swagger specific I started my work 3 days ago Will be available soon Virtus gem for type check Meta programming DSL Jiang Wu Swagger 2015-09-12 28 / 42
  29. 29. Unleash power of database API Database Routes Tables/Views Input types Constraints, Types Output types Table columns Authorizations Roles Jiang Wu Swagger 2015-09-12 29 / 42
  30. 30. Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang Wu Swagger 2015-09-12 30 / 42
  31. 31. Design philisophy Can we use the declarative information in a relational db schema to mechanically generate an HTTP API? begriffs Jiang Wu Swagger 2015-09-12 31 / 42
  32. 32. 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-09-12 32 / 42
  33. 33. 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-09-12 33 / 42
  34. 34. 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-09-12 34 / 42
  35. 35. DML -> HTTP methods insert POST update PATCH upsert/merge PUT delete DELETE Jiang Wu Swagger 2015-09-12 35 / 42
  36. 36. DB Roles -> Authorizations Need extra works to support normal database-based authentication and authorizations. Jiang Wu Swagger 2015-09-12 36 / 42
  37. 37. Why PostgREST? Counter attack to NoSQL Bare metal speed (written in Haskell) HTTP protocol Jiang Wu Swagger 2015-09-12 37 / 42
  38. 38. Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang Wu Swagger 2015-09-12 38 / 42
  39. 39. Swagger Describe REST services Provide Live testable documentation with Swagger UI Can generate with grape-swagger Disadvantage: have to investigate across components when debugging Ruby client: under work Jiang Wu Swagger 2015-09-12 39 / 42
  40. 40. PostgREST DB Schema -> API Rediscover values of RDBMS Advantage: can utilize more mature tools built around RDBMS Jiang Wu Swagger 2015-09-12 40 / 42
  41. 41. Apply DRY principle Abstract not duplicate Select proper tools Bring values Jiang Wu Swagger 2015-09-12 41 / 42
  42. 42. Q&A Questions? Twitter: @masterwujiang Github: @nouse Linkedin: @nouse Jiang Wu Swagger 2015-09-12 42 / 42

×