Consuming RESTFul APIs using Swagger v2.0

Pece Nikolovski

My Story

Can you please provide API Specification for your existing Web

Service?

THE Web Service specification

● Some .txt or .doc or email containing this...

https://my.company.api/v1/login

https://my.company.api/v1/user

https://my.company.api/v1/cards

https://my.company.api/v1/phones

https://my.company.api/v1/addresses

https://my.company.api/v1/addresses/1

THE Web Service specification v2

Push request for login using username, password and deviceId(UUID)https://my.company.api/v1/login

Get user detailshttps://my.company.api/v1/user

Get list of cardshttps://my.company.api/v1/cards

Get list of phoneshttps://my.company.api/v1/phones

•••

My approach

● Deciphering phaseo Postman

● Document Web Service o Use template doc

● Verify specification docs with client● Let the coding begin

The “Web Service Document”

Common issues

● Developers “LOVE” documentationo new api callso modification of existingo maintenance of Web Service Docs

● Consistency between platformso iOS, Android and IS

● Etc.

What is Swagger?

Swagger

What is the meaning of Swagger?

What is Swagger?

● Simple representation of your RESTful API

● Group of projectso several maino over 50 community

● http://swagger.io

Swagger Spec & Core

● Swagger syntax - Json or Yamlo I prefer Yaml

● Models using JSON Schema draft v4● https://github.com/swagger-api/swagger-spec● https://github.com/swagger-api/swagger-core

How to create the Spec?

● Two approacheso Automatico Manual

Our approach

Outware’s approach

● Why v2.0?o Why not v1.2 or v1.0

● Lots of reasons…o Java vs Scala

● Works in both cases o building API and cliento only client

Manually build the Specs

● How to check specs validity?o JSON, YAML, blah blah blah...

Swagger Editor

● Available on v2● Validation of Swagger syntax● Visually attractive

Online Validator● Swagger Validator Badge

<img src="http://online.swagger.io/validator?url={YOUR_URL}">

Swagger UI

● Web Service documentationo Interactive

● Directly test API calls and observe the results

Put validation in action

● JSON Schema Validatoro https://github.com/ruby-json-schema/json-schema

● Validate models based on spec file

What about mobile dev?

Swagger Codegen

● Generate client code based on spec● Java / Maven project● Output is auto generated ( & “documented code”)● Multiple languages support

o Language client classo Mustache template files

Android - How it works?

● Default setup - Out-Of-The-Boxo package, name, artefact id, version

● Run this command:

java -jar swagger-codegen-distribution-2.1.0.jar \ -i http://petstore.swagger.io/v2/swagger.json \ -l android \ -o samples/client/petstore/android

● Use generated code as maven dependency in Android project

Custom Android example

● Extend AndroidClientCodegen.javao make necessary changes (package, name, version, etc…)

Custom Android example

● Re-package using: mvn package● Generate client code:

java -jar swagger-codegen-distribution-2.1.0.jar \ -i http://petstore.swagger.io/v2/swagger.json \ -l au.com.outware.MyAndroidCodegen \ -o samples/client/petstore/android

What is the quality of generated code?

● Code as good as your templateo Treat as “Black Box”

● Using HTTPRequest● Errors returned as string instead models● Minor bugs

o array http paramso form params

What we wanted?

● Retrofit● OKHttp● Gradle● Proper Error Handling● Javadoc and Sources available in Android project● Outware’s fork

https://github.com/outware-mobile/swagger-codegen

How to use?

● Generate Retrofit client

java -jar swagger-codegen-distribution-2.1.0.jar \ -i http://petstore.swagger.io/v2/swagger.json \ -l android-retrofit \ -o samples/client/petstore/java

How to use?

● Local maven repo: Nexus or Artefactory (to publish .jar artefacts)

● Compile the generated code o gradle buildo Jar files in (build/libs/*)

APIs sources javadoc

● Publish artefactso gradle uploadRelease

How to use?

● Set as project dependency in build.gradle

repositories { maven { url 'http://your_maven_repo' }}...dependencies { compile 'com.wordnik:io.swagger.client:1.0.0' compile 'com.squareup.retrofit:retrofit:1.8.0' compile 'com.squareup.okhttp:okhttp-urlconnection:2.1.0' compile 'com.squareup.okhttp:okhttp:2.1.0'}

iOS - How it works?

● Same as Android● Default setup - Out-Of-The-Box

o generated files prefix● Run this command:

java -jar swagger-codegen-distribution-2.1.0.jar \ -i http://petstore.swagger.io/v2/swagger.json \ -l objc \ -o samples/client/petstore/objc

● Copy generated code and include into project

Custom iOS example

● Extend ObjcClientCodegen.javao make changes (file prefix, etc…)

Custom iOS example

● Re-package using: mvn package● Generate client code:

java -jar swagger-codegen-distribution-2.1.0.jar \ -i http://petstore.swagger.io/v2/swagger.json \ -l au.com.outware.MyObjcCodegen \ -o samples/client/petstore/objc

What we wanted

● AFNetworking v2● Project dependency as Podspec

o similar approach as with Android

target :MyProject do...

pod 'petstore-api'end

● Error Message Handling - instead of returning NSError● AppleDoc for API calls and models

Final piece of the puzzle

● Consistencyo versioningo new api speco updated api speco bugfixes in templates

● The Web Service Repoo both iOS and Android in same repo

● Automated in CIo one click release

Approach Summary

● Design API specs using ‘Swagger Editor’● Validate server responses with ‘Ruby JSON Schema Validator’ ● Publish Swagger specs using ‘Swagger UI’● Generate client code

o One repo for both iOS and Androido Android as Maven dependencyo iOS as Podspec dependency

● Update projecto Small or Big Refactoring

Summary of Issues

● v2 in “development”o Release 2.1.1-M1 on 18 Feb

● Bugs in the template files● Not yet implemented

o Json schema model inheritance not supportedo Error model handlingo More languages support in v1.2o Other issues

● Recompiling not efficiento Poorly documented codebase

What’s next?

● Contribute to main repoo Command line options

● Auth Support in Swaggero Basic, OAuth v2.0, etc.

● Other new features● Generating API integration stubs● And FINALLY...

Join the Crew

Thank You

Pece NikolovskiOutware Mobile - www.outware.com.au

The OMPodcast - All about the Mobile Industry