consuming restful apis using swagger v2.0
TRANSCRIPT
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
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?
● 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
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
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
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
● 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...