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