Swagger Codegen Android Assessment

Ref: iOS Assessment

The following is an assessment of using Swagger when developing Android apps.

General Observations

• the Swagger editor doesn’t work with Adblocker on (not relevant but come on)
• generates .md files (Markdown) for the client, which is handy.
• generates everything needed, including many things not needed:
  • uses Volley (a popular networking library) but all our projects use Retrofit (might be configurable?)
  • API code is VERY verbose
  • generates authentication code but Retrofit uses a different approach than Swagger (Retrofit intercepts requests and adds headers)

Model Classes

• generates equals, hashCode and toString methods which is nice.
• uses custom annotations eg. @ApiModelProperty(required = true, value = “”) which may or may not be useful (i’m erring on the side of not useful, they add a lot of noise to classes)
• automatically adds GSON annotations for @SerializedName which can be nice:
  • uses them on all fields even those that don’t need them which is very noisy.
  • on the other hand means the dev doesn’t need to add them when they ARE needed.
  • @SerializedName is for when the JSON has a field full_name that the deserialiser will marshal into fullName as per Java conventions.
• adds a description (if one if present in the Swagger JSON/YAML which is nice, although it’s not in Javadoc form so kinda useless)
• Uses Wrapper classes for primitives, can lead to bugs and is generally unadvised unless needed. Getters/Setters for boolean values won’t pass checkstyle (uses names like getDog instead of isDog which is Java convention)

Request Classes

• request classes are verbose and not applicable with Retrofit

Util Class

• generates a JSONUtil class which is nice but might need modification

Conclusion

The architecture of the app will need to be fundamentally different if using Swagger rather than our normal approach.

The time saved by codegen may be negated by dev learning the new approach and fixing issues but may also save time in the long run regardless of these issues.

The model class generation is the most agnostic feature of the codegen and may be helpful even without the rest of the generated code; the problem with it is that the classes may need slight alterations which will be overridden if the API is changed and new code is generated and as such would need to be modified again. The model class codegen is most useful when the API is already fully defined and won’t change much, in such a case it cuts down significant time writing boilerplate code but if the API is constantly changing this advantage MAY be overtaken by time needed to fix issues.

If Swagger is to be used to the fullest (all API calls, model classes, exceptions etc.) then the app will need to adopt the approach fully to get the most benefit (No retrofit, no/more lenient checkstyle, devs learning swaggers approach).

I believe the model class generation is the biggest benefit and may be useful regardless of the rest of the codegen.

Download the Android Swagger Client Example

2016-11-25 11:14 Update from Alex:

Swagger can generate Retrofit code which makes it a lot more lucrative than my first assessment, it even uses RxJava. We already have an internal library for this code though so i’m not sure if this changes much.

A lot of the remarks will be similar (general verbosity of the code, checkstyle errors [although iOS is not using checkstyle at the moment], requiring full dedication no half measures etc.)