Handler composition

Composing schemas together also requires that the API handler classes be compositional as well. Use the x-gw-apihandlers property on the root object to list the API handler classes that you want to compose together. The property takes an array of strings, each of which is a valid Gosu or Java class name. To determine the method for any given operation, PolicyCenter searches the listed classes, in order of listing, for the method.

It is useful to having multiple handler classes for multiple reasons.
  1. You can split the implementation of a large, complex API across several logical classes.
  2. If creating a Swagger schema that primarily serves to aggregate several other schema files together, you can simply list all the handler classes associated with those component schemas.
  3. If a Swagger schema is purely additive relative to the combined schemas, you can simply create a new handler class for the new operations, and then list both that new handler class and the handler classes for the combined schemas.
  4. If you need to override only one or two methods from an existing handler class, you can:
    1. Create a new class with the same method names.
    2. List both your new class and the existing handler class in property x-gw-apihandlers.
    3. Place the new class first in the class list so that PolicyCenter uses its methods preferentially

In addition, PolicyCenter looks preferentially for explicitly declared methods before looking at inherited methods. This behavior makes it easier to use class inheritance to extend an existing handler class.