SwaggerImplement 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 application3 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

Constraints 約束

HTTP/1.1JSON data formatREST architecture style

Jiang Wu Swagger 2015-09-12 6 / 42

Ruby Gems

grape REST servicesdoorkeeper OAuth providerThanks yorkxin’s blog for the help.

Jiang Wu Swagger 2015-09-12 7 / 42

API documentations

Must be important, clear and accurate.重要 跨專案組，跨公司清楚 減少交流成本正確 和程式碼保持同步

Jiang Wu Swagger 2015-09-12 8 / 42

程式設計師痛恨兩件事情寫⽂檔別⼈不寫⽂檔

Coders hate 2 things: writingdocumentation and no documentation.Solution’D’o not ’R’epeat ’Y’ourself Priciple

Jiang Wu Swagger 2015-09-12 9 / 42

Remove duplication

documentation -> code WSDLcode -> documentation RDoc, YARD,

Rocco(annotated source code)literate programming noweb, Org Mode,

Literate Haskell

Jiang Wu Swagger 2015-09-12 10 / 42

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

DefinitionsSwaggerDescribe REST servicesSwagger UILive testable documentationgrape-swaggerGenerate API description

Jiang Wu Swagger 2015-09-12 13 / 42

Describe REST services

API routesInput typesOutput typesAuthorizations

Jiang Wu Swagger 2015-09-12 14 / 42

Implementation 實作1 Grape basic declaration2 Namespace and routes3 ’params’ -> input type4 Grape::Entity -> output type5 Doorkeeper -> OAuth authorizations6 Swagger information

Jiang Wu Swagger 2015-09-12 15 / 42

Grape basic declarationclass API < Grape::API

# API routes prefixprefix 'api'# API versionversion 'v1', using: :path# load other APImount Endpoints

endJiang Wu Swagger 2015-09-12 16 / 42

namespaces 命名空間namespace "projects" do

mount ProjectsAPI# namepsaces can be variable# and cascadablenamespace ":identity" do

mount SingleProjectAPIend

endJiang Wu Swagger 2015-09-12 17 / 42

API routesSinatra like DSL, declared with HTTPmethods.desc "Show single project"# get|post|put|patch|deleteget "/:project" do

# Your implementationend

Jiang Wu Swagger 2015-09-12 18 / 42

Input types 輸⼊類型params do

requires :name, type: Stringoptional :public,

type: Boolean,default: false

endValidate requests and return 400 statuscode for typecast error or missing value.

Jiang Wu Swagger 2015-09-12 19 / 42

Output types 輸出類型class Project < Grape::Entity

# Output fieldsexpose :name,

documentation: {type: 'string',desc: 'Project name'

}end

Jiang Wu Swagger 2015-09-12 20 / 42

Refer to other typesclass Project < Grape::Entity

expose :owner,# with 'using'

using: Account,documentation: {

type: 'Account'}

endJiang Wu Swagger 2015-09-12 21 / 42

OAuth authorizations

Rails + doorkeeperOAuth admin pageOAuth grant flow

Grape + doorkeeperHandle OAuth token

Jiang Wu Swagger 2015-09-12 22 / 42

Swagger information (1)Delare withadd_swagger_documentation

api_versionmount_pathauthorizationsinfo

Jiang Wu Swagger 2015-09-12 23 / 42

Swagger informations (2)Add documentaions of

namespaceparamsoutput types (options of ’desc’)OAuth scopes (options of ’desc’)API codes (options of ’get’/’post’)

Jiang Wu Swagger 2015-09-12 24 / 42

Live TestSimiliar 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

API test before Swagger

Write it by yourselfBrowser plugins (not quite works)RestClient Firefox + ChromeProprietary softwaresPostman Chrome + NodeJS

Paw Mac

Jiang Wu Swagger 2015-09-12 26 / 42

Short summary of Swagger

API routesInput typesOutput typesAuthorizations

Jiang Wu Swagger 2015-09-12 27 / 42

Ruby Swagger clients

REST clients are not Swagger specificI started my work 3 days agoWill be available soonVirtus gem for type checkMeta programming DSL

Jiang Wu Swagger 2015-09-12 28 / 42

Unleash power of database

API DatabaseRoutes Tables/ViewsInput types Constraints, TypesOutput types Table columnsAuthorizations Roles

Jiang Wu Swagger 2015-09-12 29 / 42

Context

1 Introduction

2 Swagger

3 PostgREST

4 Summary

Jiang Wu Swagger 2015-09-12 30 / 42

Design philisophy

Can we use the declarativeinformation in a relational dbschema to mechanically generatean HTTP API?

begriffs

Jiang Wu Swagger 2015-09-12 31 / 42

Features of PostgreSQL

Data types Array, HStore, GIS,JSONB(since 9.4)

Procedure languages PL/pgSQL,PL/Python, PL/V8

Message queue NOTIFY/LISTENFull text search tsvector/tsquery

Jiang Wu Swagger 2015-09-12 32 / 42

Schema -> APISchema path -> API versionTables/views -> API routesWhere clause -> query params

GET/projects?age=lt.P7D&public=eq.trueQuery projects created in 7 days andpublic.

Jiang Wu Swagger 2015-09-12 33 / 42

Pagination -> Range headersGET /items HTTP/1.1Range-Unit: itemsRange: 0-24

HTTP/1.1 206 Partial ContentAccept-Ranges: itemsContent-Range: 0-24/100Range-Unit: items

Jiang Wu Swagger 2015-09-12 34 / 42

DML -> HTTP methods

insert POSTupdate PATCHupsert/merge PUTdelete DELETE

Jiang Wu Swagger 2015-09-12 35 / 42

DB Roles -> Authorizations

Need extra works to support normaldatabase-based authentication andauthorizations.

Jiang Wu Swagger 2015-09-12 36 / 42

Why PostgREST?

Counter attack to NoSQLBare metal speed (written in Haskell)HTTP protocol

Jiang Wu Swagger 2015-09-12 37 / 42

Context

1 Introduction

2 Swagger

3 PostgREST

4 Summary

Jiang Wu Swagger 2015-09-12 38 / 42

SwaggerDescribe REST servicesProvide Live testable documentationwith Swagger UICan generate with grape-swaggerDisadvantage: have to investigateacross components when debuggingRuby client: under work

Jiang Wu Swagger 2015-09-12 39 / 42

PostgREST

DB Schema -> APIRediscover values of RDBMSAdvantage: can utilize more maturetools built around RDBMS

Jiang Wu Swagger 2015-09-12 40 / 42

Apply DRY principle

Abstract not duplicateSelect proper toolsBring values

Jiang Wu Swagger 2015-09-12 41 / 42

Q&A

Questions?Twitter: @masterwujiangGithub: @nouseLinkedin: @nouse

Jiang Wu Swagger 2015-09-12 42 / 42