Miredot | Json Payload Documentation <span class="protag"/>

Reference Manual

Json Payload Documentation

Since version 1.4, Miredot PRO documents individual JSON fields (only HTML, not shown in the DOCX export). To document the fields, Miredot reads the Javadoc comments associated with the field/getter/setter methods of the classes that define the different fields of the payload. The precedence of these three locations is as follows:

For Input (body for PUT/POST operations): setter > field > getter
For output (returntypes): getter > field > setter

This is in line with how asymmetric payloads are dealt with. In the output documentation, the comments are shown by default but there is a toggle present to hide them. It is possible to override this behaviour with the jsonDoc option in the html output section. Valid values are:

Enabled: include and show the JSON Payload documentation (default)
Disabled: do not include the JSON Payload documentation
Hidden: include the JSON Payload documentation, but hide it by default.

Example:

Maven

<configuration>
    <output>
        <html>
            <jsonDoc>Hidden</jsonDoc>
        </html>
    </output>
</configuration>

Gradle

miredot {
    output {
        formats {
            'html' {
                jsonDoc = 'Hidden'
            }
        }
    }
}

Multiline documentation

By default, only the first line/sentence of the comment is shown inline. If there is more than one line of documentation, the full text is shown in a popup when hovering (since Miredot 1.6). If you do not want the latter, this can be disabled (see futher).

Example output: this code-snippet results in the documentation shown in the screenshot below.

Code example:

/**
 * This is the commentary that will be shown in the commentary widget,
 * it provides more detailed documentation.
 *
 * @return The first street line.
 */
public String getStreet1() {
    return street1;
}

Resulting output:

By default multiline comments are enabled. You can explicitly enable or disable this behavior showFullFieldDocumentationOnHover parameter. Example configurations for Maven and Gradle can be found below:

Maven:

<configuration>
    <output>
        <html>
            <showFullFieldDocumentationOnHover>
                false
            </showFullFieldDocumentationOnHover>
        </html>
    </output>
</configuration>

Gradle:

miredot {
    output {
        formats {
            'html' {
                showFullFieldDocumentationOnHover = false
            }
        }
    }
}