Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
@johannes_fiala#Devoxx #Swagger
Enhance existing REST APIs
(e.g. Facebook Graph API) with
code completion using
Swagger/Sp...
@johannes_fiala#Devoxx #Swagger
Enhance REST APIs
• Add API documentation (like WSDL schema)
• Describes the Service/reque...
@johannes_fiala#Devoxx #Swagger
Enhance REST APIs
Benefits
• Makes the payload predictable
• Allows to use tools using the...
@johannes_fiala#Devoxx #Swagger
How to enhance REST APIs?
• Ask API provider to provide Swagger apidocs
• If using Spring:...
@johannes_fiala#Devoxx #Swagger
In the next few minutes you‘ll learn
…
• Introduction to Springfox/Swagger-Codegen
• Basic...
@johannes_fiala#Devoxx #Swagger
Technology stack
• Spring
• Spring Boot for fast start
• also possible: Spring REST/MVC
• ...
@johannes_fiala#Devoxx #Swagger
Big Picture
Your REST-API
Springfox
/v2/api-docs/
Swagger-UI
/swagger/index.html
Swagger-
...
@johannes_fiala#Devoxx #Swagger
Springfox
• Provide complete api-docs for every @RESTController
• Services
• Supported Ver...
@johannes_fiala#Devoxx #Swagger
Swagger Codegen
• Client code stub generator (commandline)
• Generates completely customiz...
@johannes_fiala#Devoxx #Swagger
Swagger Codegen
• io.swagger.codegen.DefaultGenerator.generate():
• Reads api-docs in json...
@johannes_fiala#Devoxx #Swagger
Big Picture
Facebook Graph
API
Springfox
/v2/api-docs/
Swagger-
Codegen
Client-Code
Facebo...
@johannes_fiala#Devoxx #Swagger
Facebook Graph API
• Basic docs:
https://developers.facebook.com/docs/graph-
api/overview
...
@johannes_fiala#Devoxx #Swagger
Extract metadata from the Facebook
Graph API
• Facebook Graph API url:
https://graph.faceb...
@johannes_fiala#Devoxx #Swagger
Demo
• Demo of Facebook Graph API
@johannes_fiala#Devoxx #Swagger
Extract metadata from the Facebook
Graph API
• Target: Provide Swagger apidocs for Faceboo...
@johannes_fiala#Devoxx #Swagger
Preparation work
• a Facebook-Account
• Checkout/Download the demo project
https://github....
@johannes_fiala#Devoxx #Swagger
Preparation work
• Modules of the swagger-springfox-demo:
• Swagger-codegen-2.1.3-facebook...
@johannes_fiala#Devoxx #Swagger
Big Picture
Facebook Graph
API
Springfox
/v2/api-docs/
Swagger-
Codegen
Client-Code
Facebo...
@johannes_fiala#Devoxx #Swagger
Define the server proxy
• ConnectorUserFacebookController:
• Uses basic FacebookUser-model...
@johannes_fiala#Devoxx #Swagger
Demo
• Demo of Facebook server proxy
@johannes_fiala#Devoxx #Swagger
Big Picture
Facebook Graph
API
Springfox
/v2/api-docs/
Swagger-
Codegen
Client-Code
Facebo...
@johannes_fiala#Devoxx #Swagger
Add metadata fields to Swagger-
Codegen
• Add fields listed in metadata
• Add field descri...
@johannes_fiala#Devoxx #Swagger
Add metadata fields to Swagger-
Codegen
• Important class: DefaultGenerator
• Line: Model ...
@johannes_fiala#Devoxx #Swagger
Add metadata fields to Swagger-
Codegen
• Map Facebook datatypes to Swagger datatypes
// E...
@johannes_fiala#Devoxx #Swagger
Add metadata fields to Swagger-
Codegen
• Extract Enum datatypes (e.g. attire)
• Descripti...
@johannes_fiala#Devoxx #Swagger
Running the code generator
• io.swagger.codegen.Codegen -i
http://localhost:8080/v2/api-do...
@johannes_fiala#Devoxx #Swagger
View the generated code
• The FacebookUser now has all fields of the Graph API!
@ApiModel(...
@johannes_fiala#Devoxx #Swagger
Demo
• Demo of Swagger-Codegen
@johannes_fiala#Devoxx #Swagger
Big Picture
Facebook Graph
API
Springfox
/v2/api-docs/
Swagger-
Codegen
Client-Code
Facebo...
@johannes_fiala#Devoxx #Swagger
Client code:
Access Facebook directly
• Junit-Test: Facebook_Test.java
• Change basepath:
...
@johannes_fiala#Devoxx #Swagger
Adding a custom language
• See JavaFacebookClientCodegen
• Defines template-directory is J...
@johannes_fiala#Devoxx #Swagger
Running the code generator
• io.swagger.codegen.Codegen -i
http://localhost:8080/v2/api-do...
@johannes_fiala#Devoxx #Swagger
Get Swagger apidocs
• Get Swagger apidocs
• Access FB through Proxy using Swagger-UI
• See...
@johannes_fiala#Devoxx #Swagger
Demo
• Demo of Facebook server proxy
with new FacebookUser-class
@johannes_fiala#Devoxx #Swagger
Wrapup
• Learned:
• You are able to add fields dynamically to a model class during
client-...
@johannes_fiala#Devoxx #Swagger
Possible improvements
• Structures (e.g. Location) are currently not part of the
Facebook ...
@johannes_fiala#Devoxx #Swagger
Support for Beans Validation API
(JSR 303)
• Not yet implemented
• See Issue for discussio...
@johannes_fiala#Devoxx #Swagger
Support for Beans Validation API
How to add it yourself:
• Using „Plugins“ you can overrid...
@johannes_fiala#Devoxx #Swagger
Support for Beans Validation API
Further available plugins
• Available Plugins for Model/P...
@johannes_fiala#Devoxx #Swagger
Fine-Tuning Spring Boot
• Spring Boot adds /error path automatically
• Get rid of it using...
@johannes_fiala#Devoxx #Swagger
Hot Deploy using Spring Loaded
• Allows hot deploy
• for adding new methods etc.
• Add JVM...
@johannes_fiala#Devoxx #Swagger
Links & Resources
• Swagger.io
http://swagger.io/open-source-integrations/
• Springfox
htt...
@johannes_fiala#Devoxx #Swagger
Links & Resources
• Swagger UI
https://github.com/swagger-api/swagger-ui
• Swagger Codegen...
@johannes_fiala#Devoxx #Swagger
Thank you for your attention!
• Contact:
• johannes.fiala@fwd.at
Upcoming SlideShare
Loading in …5
×

Enhance existing REST APIs (e.g. Facebook Graph API) with code completion using Swagger/Spring- Devoxx 2015

2,054 views

Published on

Explains how you can add code completion to an existing third-party API (e.g. Facebook Graph API) using Swagger-Codegen

Devoxx Belgium Nov. 2015

Published in: Technology
  • Be the first to comment

Enhance existing REST APIs (e.g. Facebook Graph API) with code completion using Swagger/Spring- Devoxx 2015

  1. 1. @johannes_fiala#Devoxx #Swagger Enhance existing REST APIs (e.g. Facebook Graph API) with code completion using Swagger/Spring Johannes Fiala FWD
  2. 2. @johannes_fiala#Devoxx #Swagger Enhance REST APIs • Add API documentation (like WSDL schema) • Describes the Service/request/response/models • + add description for others to understand • In a standardized way = according to Swagger Spec. • Using a standardized structure, datatype names, references to models, …
  3. 3. @johannes_fiala#Devoxx #Swagger Enhance REST APIs Benefits • Makes the payload predictable • Allows to use tools using the Swagger-standard • Use Swagger-UI for exploring the API • Generate client code with Swagger-Codegen • Get Code completion for 20+ programming languages • Ship SDKs in target languages • Get correct datatypes in client code • Get Enum support • Get Compile-time checking of consistency
  4. 4. @johannes_fiala#Devoxx #Swagger How to enhance REST APIs? • Ask API provider to provide Swagger apidocs • If using Spring: Springfox-libraries • If not: see Swagger-Spring integrations • If not possible: • Create Swagger apidocs on your own • Demo Today: Facebook Graph API • Other REST-API‘s you‘d like to have enhanced? • Google Maps API? • ???
  5. 5. @johannes_fiala#Devoxx #Swagger In the next few minutes you‘ll learn … • Introduction to Springfox/Swagger-Codegen • Basic overview of Facebook Graph API • Step-by-step Demo of using Swagger-Codegen to extract Metadata & add them to the model • Extract standard apidocs for Facebook • Learn about using Swagger-Codegen • Support of Bean Validation API: add @NotNull/@Min/@Max by adding your own BuilderPlugins
  6. 6. @johannes_fiala#Devoxx #Swagger Technology stack • Spring • Spring Boot for fast start • also possible: Spring REST/MVC • Springfox • For generating the api-docs • Swagger UI • For accessing the api using a browser • Swagger Codegen commandline • For generating client code stubs
  7. 7. @johannes_fiala#Devoxx #Swagger Big Picture Your REST-API Springfox /v2/api-docs/ Swagger-UI /swagger/index.html Swagger- Codegen Client-Code Java, PHP, C#, Ruby, nodejs, Objective-C, …
  8. 8. @johannes_fiala#Devoxx #Swagger Springfox • Provide complete api-docs for every @RESTController • Services • Supported Verbs (GET/POST/…) • Request parameters/body • Response codes + body • Many customization options (hide attributes, custom data types, …)
  9. 9. @johannes_fiala#Devoxx #Swagger Swagger Codegen • Client code stub generator (commandline) • Generates completely customizable client stubs • Supported languages: • Java, C#, Dart, Flash, Groovy, JaxRS, NodeJS, Objective-C, Perl, PHP, Python, Ruby, Scala, …. • Ensures consistency of your client code with the API!
  10. 10. @johannes_fiala#Devoxx #Swagger Swagger Codegen • io.swagger.codegen.DefaultGenerator.generate(): • Reads api-docs in json syntax • Scans each model • Scans all the model properties • Then compiles language-specific Mustache templates using a language-specific Configuration class • Language specific configuration: • io.swagger.codegen.languages.* • Mustache files: src/main/resources
  11. 11. @johannes_fiala#Devoxx #Swagger Big Picture Facebook Graph API Springfox /v2/api-docs/ Swagger- Codegen Client-Code Facebook Proxy REST Service generates (2) calls (3) Read field metadata (1)
  12. 12. @johannes_fiala#Devoxx #Swagger Facebook Graph API • Basic docs: https://developers.facebook.com/docs/graph- api/overview • Graph API Explorer: https://developers.facebook.com/tools/explorer • Nice for basic testing • Retrieve your access token
  13. 13. @johannes_fiala#Devoxx #Swagger Extract metadata from the Facebook Graph API • Facebook Graph API url: https://graph.facebook.com/v2.5/microsoft?access_token =... &fields=name,about,mission • Get field metadata: add parameter „&metadata=1“
  14. 14. @johannes_fiala#Devoxx #Swagger Demo • Demo of Facebook Graph API
  15. 15. @johannes_fiala#Devoxx #Swagger Extract metadata from the Facebook Graph API • Target: Provide Swagger apidocs for Facebook API • Read metadata • Add description to fields • Map field types to standard datatypes • Add Enumerations • Swagger Codegen has the Model data available during processing and can be extended • Alternative: Json transformation from metadata to Swagger api
  16. 16. @johannes_fiala#Devoxx #Swagger Preparation work • a Facebook-Account • Checkout/Download the demo project https://github.com/jfiala/swagger-springfox-demo
  17. 17. @johannes_fiala#Devoxx #Swagger Preparation work • Modules of the swagger-springfox-demo: • Swagger-codegen-2.1.3-facebook • The customized Swagger-codegen code for Facbeook • User-rest-service-2.2.2-facebook • The Spring Boot REST-API application • User-rest-service-2.2.2-facebook-client-java-codegen • The generated client stubs
  18. 18. @johannes_fiala#Devoxx #Swagger Big Picture Facebook Graph API Springfox /v2/api-docs/ Swagger- Codegen Client-Code Facebook Proxy REST Service generates (2) calls (3) Read metadata (1)
  19. 19. @johannes_fiala#Devoxx #Swagger Define the server proxy • ConnectorUserFacebookController: • Uses basic FacebookUser-model (with 2 attributes) • No need to recode representation class • Connects to Facebook using Spring Rest • Try it using Swagger-UI
  20. 20. @johannes_fiala#Devoxx #Swagger Demo • Demo of Facebook server proxy
  21. 21. @johannes_fiala#Devoxx #Swagger Big Picture Facebook Graph API Springfox /v2/api-docs/ Swagger- Codegen Client-Code Facebook Proxy REST Service generates (2) calls (3) Read metadata (1)
  22. 22. @johannes_fiala#Devoxx #Swagger Add metadata fields to Swagger- Codegen • Add fields listed in metadata • Add field description • Map FB field type to Swagger standard datatype • Extract Enumerations out of description • Add JSR-303 @NotNull, (@Min, @Max) • + ??? • Add further Bean Validation Annotations (e.g. Size)? • Further suggestions?
  23. 23. @johannes_fiala#Devoxx #Swagger Add metadata fields to Swagger- Codegen • Important class: DefaultGenerator • Line: Model model = definitions.get(name); String access_token =„…"; String url = "https://graph.facebook.com/pivotalsoftware?access_token=" + access_token + "&metadata=1"; FacebookUser user = readJsonFromUrl(url); for (FacebookField field : user.getMetadata().getFields()) { propName = field.getName(); // add new virtual fields from Facebook to the model virtualProperty = new StringProperty(); virtualProperty.setName(propName); virtualProperty.setDescription(field.getDescription()); model.getProperties().put(propName, virtualProperty); }
  24. 24. @johannes_fiala#Devoxx #Swagger Add metadata fields to Swagger- Codegen • Map Facebook datatypes to Swagger datatypes // Examples of data type mappings from Facebook-Datatypes to Swagger-Model-Datatypes if ("bool".equals(field.getType())) { virtualProperty = new BooleanProperty(); } else if ("unsigned int32".equals(field.getType())){ virtualProperty = new IntegerProperty(); } else { virtualProperty = new StringProperty(); }
  25. 25. @johannes_fiala#Devoxx #Swagger Add metadata fields to Swagger- Codegen • Extract Enum datatypes (e.g. attire) • Description: "Dress code of the business. Applicable to Restaurants or Nightlife. Can be one of Casual, Dressy or Unspecified“ StringProperty myStringProperty = (StringProperty)virtualProperty; String myEnumValues = StringUtils.substringAfter(field.getDescription(), "Can be one of"); myEnumValues = StringUtils.replace(myEnumValues, " or ", ", "); String[] enumValues = StringUtils.split(myEnumValues); for (String myEnum : enumValues) { myStringProperty._enum(myEnum ); }
  26. 26. @johannes_fiala#Devoxx #Swagger Running the code generator • io.swagger.codegen.Codegen -i http://localhost:8080/v2/api-docs/ -l java –o ../facebook- client-java
  27. 27. @johannes_fiala#Devoxx #Swagger View the generated code • The FacebookUser now has all fields of the Graph API! @ApiModel(description = "") public class FacebookUser { /** * Information about the Page **/ @ApiModelProperty(value = "Information about the Page") @JsonProperty("about") public String getAbout() { return about; } …
  28. 28. @johannes_fiala#Devoxx #Swagger Demo • Demo of Swagger-Codegen
  29. 29. @johannes_fiala#Devoxx #Swagger Big Picture Facebook Graph API Springfox /v2/api-docs/ Swagger- Codegen Client-Code Facebook Proxy REST Service generates (2) calls (3) Read metadata (1)
  30. 30. @johannes_fiala#Devoxx #Swagger Client code: Access Facebook directly • Junit-Test: Facebook_Test.java • Change basepath: // TODO Step 1: replace basepath api.getApiClient().setBasePath("https://graph.faceboo k.com/v2.5/");
  31. 31. @johannes_fiala#Devoxx #Swagger Adding a custom language • See JavaFacebookClientCodegen • Defines template-directory is JavaFacebook • Now we can modify the Model • Add @NotNull • Add @Min, @Max
  32. 32. @johannes_fiala#Devoxx #Swagger Running the code generator • io.swagger.codegen.Codegen -i http://localhost:8080/v2/api-docs/ -l java –o ../facebook- client-java
  33. 33. @johannes_fiala#Devoxx #Swagger Get Swagger apidocs • Get Swagger apidocs • Access FB through Proxy using Swagger-UI • See model definitions in the browser • Replace the model class „FacebookUser“ • Restart Spring Boot • Inspect the updated model using the Swagger-UI http://localhost:8080/swagger/index.html
  34. 34. @johannes_fiala#Devoxx #Swagger Demo • Demo of Facebook server proxy with new FacebookUser-class
  35. 35. @johannes_fiala#Devoxx #Swagger Wrapup • Learned: • You are able to add fields dynamically to a model class during client-code-generation, add datatype-mapping and enums • You are able to access the Facebook Graph API directly • You are able to add custom languages • Benefits: • You can generate client code for every language supported by Swagger-Codegen • You have code completion for all model attributes!
  36. 36. @johannes_fiala#Devoxx #Swagger Possible improvements • Structures (e.g. Location) are currently not part of the Facebook metadata and need to be created manually as representation classes • Some fields are only accessible with specific permissions, but that‘s also not visible in the metadata • See Helper-class AssembleFieldsUtil for details • JSR-303 support needs further improvement • @Min/@Max, @Size, …
  37. 37. @johannes_fiala#Devoxx #Swagger Support for Beans Validation API (JSR 303) • Not yet implemented • See Issue for discussion: https://github.com/springfox/springfox/issues/356 • Can be done using extensions (Plugin Builders)
  38. 38. @johannes_fiala#Devoxx #Swagger Support for Beans Validation API How to add it yourself: • Using „Plugins“ you can override/add to the behaviour of Builders for Parameters/the Model • Add a component implementing the Plugin-Interface, e.g. ModelPropertyBuilderPlugin • You get access to the processing context • You can query for annotations there • Examples: @NotNull, @Min/@Max
  39. 39. @johannes_fiala#Devoxx #Swagger Support for Beans Validation API Further available plugins • Available Plugins for Model/Parameters: • ModelBuilderPlugin • ModelPropertyBuilderPlugin • ParameterBuilderPlugin
  40. 40. @johannes_fiala#Devoxx #Swagger Fine-Tuning Spring Boot • Spring Boot adds /error path automatically • Get rid of it using new Docket(…)… .apis(Predicates.not(RequestHandlerSelectors.basePack age("org.springframework.boot")))
  41. 41. @johannes_fiala#Devoxx #Swagger Hot Deploy using Spring Loaded • Allows hot deploy • for adding new methods etc. • Add JVM parameters: • -javaagent:/path_to_spring-loaded/springloaded- 1.2.4.RELEASE.jar -noverify • https://github.com/spring-projects/spring-loaded • http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#howto-hotswapping
  42. 42. @johannes_fiala#Devoxx #Swagger Links & Resources • Swagger.io http://swagger.io/open-source-integrations/ • Springfox http://springfox.github.io/springfox/
  43. 43. @johannes_fiala#Devoxx #Swagger Links & Resources • Swagger UI https://github.com/swagger-api/swagger-ui • Swagger Codegen https://github.com/swagger-api/swagger-codegen • Chrome Plugin Swagger.ed https://github.com/chefArchitect/apispots-browser- swaggered
  44. 44. @johannes_fiala#Devoxx #Swagger Thank you for your attention! • Contact: • johannes.fiala@fwd.at

×