Java and JAX-RS: auto generate class containing all resources

[giovannibotta]

The generated Java API is composed of a bunch of classes each representing a JAX-RS resource. I am ok with this code structure, but I'd like to have an additional class that encapsulate those in order to set once and for all the api key or the base path of the endpoints. It would be something like this:

class Api {
  String token, path;
  SomeApi getSomeApi(){
    return new SomeApi(token, path);
  }
  SomeOtherApi getSomeOtherApi(){
    return new SomeApi(token, path);
  }
}

In this way the clients only have to create an instance of Api with the correct token and base path and that'll get propagated. It's like a giant builder class basically.

Is it possible to write a mustache file that uses each resource and creates these methods? There would obviously be a convention for the constructor.

[giovannibotta]

I tried this mustache file:

package {{package}};

public class MyClient {

  public MyClient(String basePath, String token){
    this.basePath = basePath;
    this.token = token;
  }

  private final String basePath, token;

  {{#operations}} // I also tried operation here...
  {{classname}} get{{classname}}(){
    return new {{classname}}(basePath, token);
  }
  {{/operations}}
}

and added it to the support files, but, although two api classes are generated, the generated file is:

  public MyClient(String basePath, String token){
    this.basePath = basePath;
    this.token = token;
  }

  private final String basePath, token;
}

[giovannibotta]

So I figured that out:

{{#apis}}
private {{className}} i{{className}};
{{/apis}}
{{#apis}}
{{className}} get{{className}}(){
  if(i{{className}}==null) i{{className}} = new {{className}}(basePath, token);
  return i{{className}};
}

Now I am facing a mismatch between what is available to the API mustache files, i.e., api.mustache, and what is available to the supporting classes. IMO it should be the same, but it's not, as per the example above. For example there is no way to access the method returnType or its allParams from the supporting class mustache. Is there a reason for this? Can this be changed?

[fehguy]

Hi, it should be the exact same data between the api generation and the supportingFiles:

https://github.com/wordnik/swagger-codegen/blob/master/src/main/scala/com/wordnik/swagger/codegen/Codegen.scala#L590

You shoulds be able to iterate over the {{#apis}} all the same. Can you hack the codegen.scala and have it print out the contents of the map, around line 589?

[giovannibotta]

It's not. writeSupportingClasses receives the raw Operation object. The individual API classes are generated using a map created by apiToMap which massages the Operation object making it more code-friendly. Thus parameters such as returnType or allParams are not available to use in the supporting classes templates.

[fehguy]

Got it. We need to run the apiToMap and ModelToMap in the Codegen.scala. If you have a chance to give it a shot, I'll QA & merge it, it should be easy.

[giovannibotta]

Will give it a shot.

[giovannibotta]

So digging into the writeSupportingClasses method, I noticed that modelToMap is already called there at line 580:

"model" -> modelToMap(m._1, m._2),

I also see at line 569:

"operations" -> {
  (for (t <- a._2) yield { Map("operation" -> t._2, "path" -> t._1) }).toList
})

I believe this could be replaced with:

"operations" -> {
  (for (t <- a._2) yield { Map("operation" -> apiToMap(t._1, t._2), "path" -> t._1) }).toList
})

However, I am not sure if the mustache file are gonna break since some of the keys in the map have different names than the fields in the Operation case class. Moreover, I don't see why this 'mappification' of the apis and models must be done more than once. I think this can be done at class creation once and for all and then the two mega maps can be used throughout the code. This will make it more robust. Again, though I am wondering if that'll break the mustache files.

Thoughts?

[giovannibotta]

As a side note, a few thoughts about the apiToMap and modelToMap methods.

Since scalate seems to support case classes out of the box, it might be easier to just translate the Operation and Model object to case classes instead of maps, say, case class TranslatedOperation(...) and case class TranslatedModel(...). Then for example, TranslatedOperation will have all the fields that apiToMap creates and an additional constructor that takes a Operation instance and does the translation for you. That will make the code a little cleaner and more readable, since the intent of the translation will be very clear and the logic will be all in the constructor instead of in a for comprehension hidden in the apiToMap method. It will also be more robust since whenever Operation or Model change you just need to change the TranslatedOperation and TranslatedModel constructors.

These are not necessarily changes required right now but IMO a good design overhaul for the future.

[giovannibotta]

One more question: I see no test for the code that creates supporting files. Should I add one?

[fehguy]

The codegen is going to get some rework to take away the maps. The reason it's so loosely typed is because you may need to add maps inside maps, or other structural types. For that reason, you can argue that the JVM isn't the best vehicle for codegen.

Yes, tests would be greatly appreciated.

[giovannibotta]

Yeah in order to add the test I think the code needs to become more "testable", i.e., it's a little monolithic. The code that generates supporting files is all in writeSupportingClasses, so it's hard to test in isolation. It would be nice to separate the writing to disk and the map creation from the code generation. Is there a plan to modularize this a little?