AirJD 焦点
AirJD

没有录音文件
00:00/00:00
加收藏

Swagger Implement Web API documents by Jiang Wu

发布者 ruby
发布于 1447808757182  浏览 2703 关键词 java, Ruby, English 
分享到

第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



支持文件格式:*.ppt, *.pptx, *.pdf
上传最后阶段需要进行在线转换,可能需要1~2分钟,请耐心等待。