Consuming Restful APIs using Swagger v2.0

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