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.

1. Swagger
Implement Web API documents
Jiang Wu
2015-09-12
Jiang Wu Swagger 2015-09-12 1 / 42

2. Context
1 Introduction
2 Swagger
3 PostgREST
4 Summary
Jiang Wu Swagger 2015-09-12 2 / 42

3. Do you remember this?
Jiang Wu Swagger 2015-09-12 3 / 42

4. 本尊在此 It’s me!
Jiang Wu Swagger 2015-09-12 4 / 42

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. Constraints 約束
HTTP/1.1
JSON data format
REST architecture style
Jiang Wu Swagger 2015-09-12 6 / 42

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. API documentations
Must be important, clear and accurate.
重要 跨專案組，跨公司
清楚 減少交流成本
正確 和程式碼保持同步
Jiang Wu Swagger 2015-09-12 8 / 42

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. 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. Context
1 Introduction
2 Swagger
3 PostgREST
4 Summary
Jiang Wu Swagger 2015-09-12 11 / 42

12. Demo
https://api.gitcafe.com/apidoc/
Jiang Wu Swagger 2015-09-12 12 / 42

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. Describe REST services
API routes
Input types
Output types
Authorizations
Jiang Wu Swagger 2015-09-12 14 / 42

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. 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. 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. 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. 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. 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. 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. OAuth authorizations
Rails + doorkeeper
OAuth admin page
OAuth grant flow
Grape + doorkeeper
Handle OAuth token
Jiang Wu Swagger 2015-09-12 22 / 42

23. Swagger information (1)
Delare with
add_swagger_documentation
api_version
mount_path
authorizations
info
Jiang Wu Swagger 2015-09-12 23 / 42

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. 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. 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. Short summary of Swagger
API routes
Input types
Output types
Authorizations
Jiang Wu Swagger 2015-09-12 27 / 42

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. 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. Context
1 Introduction
2 Swagger
3 PostgREST
4 Summary
Jiang Wu Swagger 2015-09-12 30 / 42

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. 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. 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. 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. DML -> HTTP methods
insert POST
update PATCH
upsert/merge PUT
delete DELETE
Jiang Wu Swagger 2015-09-12 35 / 42

36. DB Roles -> Authorizations
Need extra works to support normal
database-based authentication and
authorizations.
Jiang Wu Swagger 2015-09-12 36 / 42

37. Why PostgREST?
Counter attack to NoSQL
Bare metal speed (written in Haskell)
HTTP protocol
Jiang Wu Swagger 2015-09-12 37 / 42

38. Context
1 Introduction
2 Swagger
3 PostgREST
4 Summary
Jiang Wu Swagger 2015-09-12 38 / 42

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. 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. Apply DRY principle
Abstract not duplicate
Select proper tools
Bring values
Jiang Wu Swagger 2015-09-12 41 / 42

42. Q&A
Questions?
Twitter: @masterwujiang
Github: @nouse
Linkedin: @nouse
Jiang Wu Swagger 2015-09-12 42 / 42