Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
Build API with Swagger
Wu Jiang
October 12, 2015
Programming
2
520
Build API with Swagger
Wu Jiang
October 12, 2015
Tweet
Share
Other Decks in Programming
See All in Programming
The strategies behind ddd – AdeoDevSummit 2022
lilobase
PRO
4
240
NEWT.net: Frontend Technology Selection
xpromx
0
170
GDG Seoul IO Extended 2022 - Android Compose
taehwandev
0
290
engineer
spacemarket
0
750
Beyond Micro Frontends: Frontend Moduliths for the Enterprise @enterjs2022
manfredsteyer
PRO
0
130
Value and Record Types
hschwentner
0
550
I/O Extended 2022 in Android ~ Whats new in Android development tools
pluu
0
530
io22 extended What's new in app performance
veronikapj
0
330
はてなフォトライフをECSに移行した話 / Hatena Engineer Seminar #20
cohalz
1
820
短納期でローンチした新サービスをJavaで開発した話/launched new service using Java
eichisanden
6
1.9k
Baseline Profilesでアプリのパフォーマンスを向上させる / Improve app performance with Baseline Profiles
numeroanddev
0
230
#JJUG_CCC 「サポート」は製品開発? - JDBCライブラリ屋さんが実践する攻めのテクニカルサポートとJavaエンジニアのキャリアについて -
cdataj
0
410
Featured
See All Featured
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
37
3.2k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
498
130k
Building Adaptive Systems
keathley
25
1.1k
Building Flexible Design Systems
yeseniaperezcruz
310
34k
What’s in a name? Adding method to the madness
productmarketing
11
1.6k
Clear Off the Table
cherdarchuk
79
280k
Teambox: Starting and Learning
jrom
123
7.7k
JazzCon 2018 Closing Keynote - Leadership for the Reluctant Leader
reverentgeek
172
8.4k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
655
120k
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
151
13k
Principles of Awesome APIs and How to Build Them.
keavy
113
15k
Making the Leap to Tech Lead
cromwellryan
113
7.4k
Transcript
Swagger Implement Web API documents Jiang Wu 2015-10-11 Jiang Wu
Swagger 2015-10-11 1 / 49
Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang
Wu Swagger 2015-10-11 2 / 49
Do you remember this? Jiang Wu Swagger 2015-10-11 3 /
49
本尊在此 It’s me! Jiang Wu Swagger 2015-10-11 4 / 49
Oops!…I did it again Figure: RubyConf Taiwan 2015 Jiang Wu
Swagger 2015-10-11 5 / 49
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
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
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
Constraints HTTP/1.1 JSON data format REST architecture style Jiang Wu
Swagger 2015-10-11 9 / 49
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
Components Rails + doorkeeper OAuth admin page OAuth grant flow
Grape + doorkeeper Handle OAuth token Jiang Wu Swagger 2015-10-11 11 / 49
API documentations Must be significant, clear and accurate. 重要 跨项⽬组,跨公司
清楚 减少交流成本 正确 和代码保持同步 Jiang Wu Swagger 2015-10-11 12 / 49
程序员最痛恨两件事 写⽂档 别⼈不写⽂档 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
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
REST API specifications Swagger RAML Blueprint Jiang Wu Swagger 2015-10-11
15 / 49
Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang
Wu Swagger 2015-10-11 16 / 49
Demo https://api.gitcafe.com/apidoc/ Jiang Wu Swagger 2015-10-11 17 / 49
Definitions Swagger Describe REST services Swagger UI Live testable documentation
grape-swagger Generate API description Jiang Wu Swagger 2015-10-11 18 / 49
Describe REST services API routes Input types Output types Authorizations
Jiang Wu Swagger 2015-10-11 19 / 49
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
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
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
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
Input types params do requires :name, type: String optional :public,
type: Boolean, default: false end Jiang Wu Swagger 2015-10-11 24 / 49
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
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
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
Swagger information (1) Delare with add_swagger_documentation api_version mount_path authorizations info
Jiang Wu Swagger 2015-10-11 28 / 49
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
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
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
Short summary of Swagger API routes Input types Output types
Authorizations Jiang Wu Swagger 2015-10-11 32 / 49
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
WebView or not? 1st edition, use WebView 2nd edition, native
view 3rd edition, WebView (Electron) Jiang Wu Swagger 2015-10-11 34 / 49
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
Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang
Wu Swagger 2015-10-11 36 / 49
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
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
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
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
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
DML -> HTTP methods insert POST update PATCH upsert/merge PUT
delete DELETE Jiang Wu Swagger 2015-10-11 42 / 49
DB Roles -> Authorizations Need extra work to support normal
database-based authentication and authorizations. Jiang Wu Swagger 2015-10-11 43 / 49
Why PostgREST? Counter attack to NoSQL Bare metal speed (written
in Haskell) HTTP protocol Jiang Wu Swagger 2015-10-11 44 / 49
Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang
Wu Swagger 2015-10-11 45 / 49
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
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
Apply DRY principle Abstract instead of duplicate Select proper tools
Bring values Jiang Wu Swagger 2015-10-11 48 / 49
Q&A Questions? Twitter: @masterwujiang Github: @nouse Linkedin: @nouse Jiang Wu
Swagger 2015-10-11 49 / 49