Consuming Restful APIs using Swagger v2.0

1. Consuming RESTFul APIs using
Swagger v2.0
Pece Nikolovski

2. My Story
Can you please provide API Specification for
your existing Web Service?

3. 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

4. THE Web Service specification v2
Push request for login using username, password and deviceId(UUID)
https://my.company.api/v1/login
Get user details
https://my.company.api/v1/user
Get list of cards
https://my.company.api/v1/cards
Get list of phones
https://my.company.api/v1/phones
•••

5. My approach
● Deciphering phase
o Postman
● Document Web Service
o Use template doc
● Verify specification docs with client
● Let the coding begin

6. The “Web Service Document”

7. Common issues
● Developers “LOVE” documentation
o new api calls
o modification of existing
o maintenance of Web Service Docs
● Consistency between platforms
o iOS, Android and IS
● Etc.

8. What is Swagger?

9. Swagger

10. What is the meaning of Swagger?

11. What is Swagger?
● Simple representation of your RESTful
API
● Group of projects
o several main
o over 50 community
● http://swagger.io

12. Swagger Spec & Core
● Swagger syntax - Json or Yaml
o I prefer Yaml
● Models using JSON Schema draft v4
● https://github.com/swagger-api/swagger-spec
● https://github.com/swagger-api/swagger-core

13. How to create the Spec?
● Two approaches
o Automatic
o Manual

14. Our approach

15. 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 client
o only client

16. Manually build the Specs
● How to check specs validity?
o JSON, YAML, blah blah blah...

17. 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}">

18. Swagger UI
● Web Service documentation
o Interactive
● Directly test API calls and observe the results

19. Put validation in action
● JSON Schema Validator
o https://github.com/ruby-json-schema/json-schema
● Validate models based on spec file

20. What about mobile dev?

21. Swagger Codegen
● Generate client code based on spec
● Java / Maven project
● Output is auto generated ( & “documented code”)
● Multiple languages support
o Language client class
o Mustache template files

22. Android - How it works?
● Default setup - Out-Of-The-Box
o 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

23. Custom Android example
● Extend AndroidClientCodegen.java
o make necessary changes (package, name, version, etc…)

24. 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

25. What is the quality of generated code?
● Code as good as your template
o Treat as “Black Box”
● Using HTTPRequest
● Errors returned as string instead models
● Minor bugs
o array http params
o form params

26. 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

27. 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

28. How to use?
● Local maven repo: Nexus or Artefactory (to publish .jar artefacts)
● Compile the generated code
o gradle build
o Jar files in (build/libs/*)
 APIs
 sources
 javadoc
● Publish artefacts
o gradle uploadRelease

29. 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'
}

30. 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

31. Custom iOS example
● Extend ObjcClientCodegen.java
o make changes (file prefix, etc…)

32. 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

33. 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

34. Final piece of the puzzle
● Consistency
o versioning
o new api spec
o updated api spec
o bugfixes in templates
● The Web Service Repo
o both iOS and Android in same repo
● Automated in CI
o one click release

35. 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 Android
o Android as Maven dependency
o iOS as Podspec dependency
● Update project
o Small or Big Refactoring

36. 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 supported
o Error model handling
o More languages support in v1.2
o Other issues
● Recompiling not efficient
o Poorly documented codebase

37. What’s next?
● Contribute to main repo
o Command line options
● Auth Support in Swagger
o Basic, OAuth v2.0, etc.
● Other new features
● Generating API integration stubs
● And FINALLY...

38. Join the Crew

39. Thank You
Pece Nikolovski
Outware Mobile - www.outware.com.au
The OMPodcast - All about the Mobile Industry