Se ha denunciado esta presentación.
Utilizamos tu perfil de LinkedIn y tus datos de actividad para personalizar los anuncios y mostrarte publicidad más relevante. Puedes cambiar tus preferencias de publicidad en cualquier momento.

Consuming Restful APIs using Swagger v2.0

16.711 visualizaciones

Publicado el

Consuming Restful APIs using Swagger v2.0

Publicado en: Software
  • Sé el primero en comentar

Consuming Restful APIs using Swagger v2.0

  1. 1. Consuming RESTFul APIs using Swagger v2.0 Pece Nikolovski
  2. 2. My Story Can you please provide API Specification for your existing Web Service?
  3. 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. 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. 5. My approach ● Deciphering phase o Postman ● Document Web Service o Use template doc ● Verify specification docs with client ● Let the coding begin
  6. 6. The “Web Service Document”
  7. 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. 8. What is Swagger?
  9. 9. Swagger
  10. 10. What is the meaning of Swagger?
  11. 11. What is Swagger? ● Simple representation of your RESTful API ● Group of projects o several main o over 50 community ● http://swagger.io
  12. 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. 13. How to create the Spec? ● Two approaches o Automatic o Manual
  14. 14. Our approach
  15. 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. 16. Manually build the Specs ● How to check specs validity? o JSON, YAML, blah blah blah...
  17. 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. 18. Swagger UI ● Web Service documentation o Interactive ● Directly test API calls and observe the results
  19. 19. Put validation in action ● JSON Schema Validator o https://github.com/ruby-json-schema/json-schema ● Validate models based on spec file
  20. 20. What about mobile dev?
  21. 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. 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. 23. Custom Android example ● Extend AndroidClientCodegen.java o make necessary changes (package, name, version, etc…)
  24. 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. 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. 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. 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. 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. 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. 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. 31. Custom iOS example ● Extend ObjcClientCodegen.java o make changes (file prefix, etc…)
  32. 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. 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. 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. 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. 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. 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. 38. Join the Crew
  39. 39. Thank You Pece Nikolovski Outware Mobile - www.outware.com.au The OMPodcast - All about the Mobile Industry

×