Type Replacement

Miredot automatically maps Java types to JSON types. There are a few categories of these mappings.

1. Primitive types (and some others) are mapped to json primitive types (string, number, boolean)
2. All collection types are mapped to JSON arrays
3. All map types are mapped to JSON objects
4. A few special classes such as dates, bytes get their own JSON type
5. Complex types are expanded to JSON objects recursively

A complete list of mappings can be found in the table below.

If you are not satisfied with the default mapping or you want to override some types (replace type A by type B for documentation purposes), you can override this behavior.

Literal replacement

If you want to visualize a type as a basic JSON type, you must use a literal replacement.

For example, if you want to make a distinction between integer and floating point numbers, you can do this:

Maven

<configuration>
    <restModel>
        <typeReplacements>
            <typeReplacement>
                <source>float</source>
                <target>floatnumber</target>
                <type>literal</type>
            </typeReplacement>
            <typeReplacement>
                <source>int</source>
                <target>intnumber</target>
                <type>literal</type>
            </typeReplacement>
        </typeReplacements>
   </restModel>
</configuration>

Gradle

miredot {
    restModel {
        typeReplacement {
            'float' { 
                target = 'floatnumber'
                type = 'literal' 
            }
            'int' {
                target = 'intnumber'
                type = 'literal'
            }
        }
    }
}

This will cause the Java primitive types int and float to be documented as intnumber and floatnumber instead of the standard number. Another example is when you are using a specific date/time format (e.g., the number of seconds since epoch) and you want to indicate this in the JSON type.

Maven

<configuration>
    <restModel>
        <typeReplacements>
            <typeReplacement>
                <source>java.util.Date</source>
                <target>Seconds since Epoch</target>
                <type>literal</type>
            </typeReplacement>
        </typeReplacements>
   </restModel>
</configuration>

Gradle

miredot {
    restModel {
        typeReplacement {
            'java.util.Date' {
                target = 'Seconds since Epoch'
                type = 'literal'
            }
        }
    }
}

Alternative Type Replacement

This strategy allows you to globally replace classes for documentation purposes. Suppose a method returns MyClass, than you can configure Miredot to always treat this as YourClass.

An important use case is when you are using a custom serializer (see Jackson) for MyClass, meaning there is no direct correlation between the properties of MyClass and its JSON representation. In that case you can specify the JSON serialisation in YourClass and replace the former by the latter.

For example, suppose you have a class Person

package myPackage;
public class Person {
    getName() {};
    getSurname() {};
}

... which is by default serialized as follows:

{
    name: string,
    surname: string
}

But, you have a custom serializer which outputs this serialisation:

{
    fullName: string
}

.. than you can define the following class/interface

package yourPackage;
public interface JsonPerson {
    String getFullName(); // For output serialization
    void setFullName(String input); // For input deserialization
}

and replace Person with PersonJson

Maven

<configuration>
    <restModel>
        <typeReplacements>
            <typeReplacement>
                <source>myPackage.Person</source>
                <target>yourPackage.JsonPerson</target>
                <type>alternative</type>
            </typeReplacement>
        </typeReplacements>
   </restModel>
</configuration>

Gradle

miredot {
    restModel {
        typeReplacement {
            'myPackage.Person' {
                target = 'yourPackage.JsonPerson'
                type = 'alternative'
            }
        }
    }
}

Note that the source and target elements expect fully qualified type names.

Alternatives with generics

You can also specify generic types as your source and target types. Say for example that you have a class myPackage.MyList<T> and you want to replace all occurrences of java.util.List with this type, then you can do the following:

Maven

<configuration>
    <restModel>
        <typeReplacements>
            <typeReplacement>
                <source>java.util.List</source>
                <target>myPackage.MyList</target>
                <type>alternative</type>
            </typeReplacement>
        </typeReplacements>
   </restModel>
</configuration>

Gradle

miredot {
    restModel {
        typeReplacement {
            'java.util.List' {
                target = 'myPackage.MyList'
                type = 'alternative'
            }
        }
    }
}

This will for example replace List<MyClass> with MyList<MyClass>. Note that the number of generic parameters of the source and target types must match. If they don't you must specify how the generic arguments must be transformed. If for example you want to replace myPackage.MyClass<T> with java.util.Map<String, java.util.List<T>>, you can do the following:

Maven

<configuration>
    <restModel>
        <typeReplacements>
            <typeReplacement>
                <source>myPackage.MyClass&lt;T&gt;</source>
                <target>java.util.Map&lt;String, java.util.List&lt;T&gt:&gt;</target>
                <type>alternative</type>
            </typeReplacement>
        </typeReplacements>
   </restModel>
</configuration>

Gradle

miredot {
    restModel {
        typeReplacement {
            'myPackage.MyClass<T>' {
                target = 'java.util.Map<String, java.util.List<T>>'
                type = 'alternative'
            }
        }
    }
}

Standard Type Mappings

The following java types are mapped to JSON Types by default, using standard literal typereplacements.