Skip to main content

@Example Annotation

The @Example annotation in org.apache.juneau.marshall identifies a canonical example instance of a POJO. Juneau surfaces these examples in generated Swagger/OpenAPI documents and uses them wherever a representative value of a type is needed.

@Example can be placed on a static method, a static field, or a class, and can also be applied to @Rest-annotated classes and @RestOp-annotated methods via @ExampleApply.

On a Static Method​

A public static method annotated with @Example that returns an instance of the enclosing type supplies the example. The method takes either zero arguments or a single MarshallingSession argument.

public class Address {

    public String street;
    public String city;

    @Example
    public static Address example() {
        Address a = new Address();
        a.street = "123 Main St";
        a.city = "Springfield";
        return a;
    }
}

The example is then emitted when the type is serialized as a documentation example:

String json = Json5.DEFAULT.of(Address.example());   // {street:'123 Main St',city:'Springfield'}

example Method Convention​

A public static method simply named example (with no arguments or one MarshallingSession argument) is picked up as the example even without the annotation:

public class Address {
    public static Address example() { ... }   // recognized by name
}

On a Static Field​

A public static field annotated with @Example supplies the example directly:

public class Address {

    public String street;
    public String city;

    @Example
    public static final Address EXAMPLE = create("123 Main St", "Springfield");
}

On a Class (JSON5 String Form)​

Applied to a class, @Example takes a Lax-JSON (JSON5) string value describing the example — no separate factory method or field is needed:

@Example("{street:'123 Main St',city:'Springfield'}")
public class Address {
    public String street;
    public String city;
}

The @Marshalled(example) Equivalent​

The same JSON5 example can be declared through the @Marshalled(example) attribute, which is useful when you are already using @Marshalled for other marshalling settings:

@Marshalled(example="{street:'123 Main St',city:'Springfield'}")
public class Address {
    public String street;
    public String city;
}

Both the class-level @Example("...") form and the @Marshalled(example="...") form set the same underlying POJO example.

Variable Resolution​

The JSON5 string forms support VarResolver.DEFAULT substitution, so an example value can reference configuration and other variables that are resolved when the example is read:

@Marshalled(example="{apiKey:'$C{Demo/apiKey}'}")
public class Credentials {
    public String apiKey;
}

See VarResolver.DEFAULT for the set of built-in variables.

Precedence​

When more than one example source is present for a type, Juneau resolves them in this order:

  1. The JSON5 string form — @Example("...") on the class or @Marshalled(example="...").
  2. An example method — a static method annotated with @Example or named example.
  3. An @Example-annotated static field.

The first source that is present wins.

See Also