Miredot | Code Analysis

Reference Manual

Code Analysis

Miredot analyses your REST interfaces and detects possible issues regarding documentation quality and possible bugs. A report of those issues is added to the generated documentation (HTML output only). Check the issues section of our example docs.

It is possible to change the behaviour of Miredot with respect to each error/issue-type, either to ignore a certain issue altogether (i.e. it will not be added to the documentation), or to make Miredot fail the build whenever an issue of the specified type occurs.

To do so, specify an <checks> block to analysis section of your configuration containing the desired severity (ignore, warn or failbuild) of the issue types you wish to reconfigure. For example:

Maven

<configuration>
    <analysis>
        <checks>
            <JAVADOC_MISSING_SUMMARY>warn</JAVADOC_MISSING_SUMMARY>
            <JAVADOC_MISSING_INTERFACEDOCUMENTATION>warn</JAVADOC_MISSING_INTERFACEDOCUMENTATION>
            <JAVADOC_MISSING_PARAMETER_DOCUMENTATION>warn</JAVADOC_MISSING_PARAMETER_DOCUMENTATION>
            <JAVADOC_MISSING_EXCEPTION_DOCUMENTATION>warn</JAVADOC_MISSING_EXCEPTION_DOCUMENTATION>
            <JAVADOC_MISSING_AUTHORS>ignore</JAVADOC_MISSING_AUTHORS>
            <JAXRS_MISSING_PATH_PARAM>warn</JAXRS_MISSING_PATH_PARAM>
            <JAXRS_MISSING_PRODUCES>warn</JAXRS_MISSING_PRODUCES>
            <JAXRS_MISSING_CONSUMES>warn</JAXRS_MISSING_CONSUMES>
            <REST_UNMAPPED_EXCEPTION>failbuild</REST_UNMAPPED_EXCEPTION>
            <UNREACHABLE_RESOURCE>warn</UNREACHABLE_RESOURCE>
            <PARTIAL_RESOURCE_OVERLAP>warn</PARTIAL_RESOURCE_OVERLAP>
            <INVALID_PATH>warn</INVALID_PATH>
            <JSON_SCHEMA_TOO_LARGE>warn</JSON_SCHEMA_TOO_LARGE>
        </checks>
    </analysis>
</configuration>

Gradle

miredot {
    analysis {
        checks = [
            JAVADOC_MISSING_SUMMARY: 'warn',
            JAVADOC_MISSING_INTERFACEDOCUMENTATION: 'warn',
            JAVADOC_MISSING_PARAMETER_DOCUMENTATION: 'warn',
            JAVADOC_MISSING_EXCEPTION_DOCUMENTATION: 'warn',
            JAVADOC_MISSING_AUTHORS: 'ignore',
            JAXRS_MISSING_PATH_PARAM: 'warn'
            JAXRS_MISSING_PRODUCES: 'warn',
            JAXRS_MISSING_CONSUMES: 'warn',
            REST_UNMAPPED_EXCEPTION: 'failbuild',
            UNREACHABLE_RESOURCE: 'warn',
            PARTIAL_RESOURCE_OVERLAP: 'warn',
            INVALID_PATH: 'warn',
            JSON_SCHEMA_TOO_LARGE: 'warn'
        ]
    }
}

The example configuration above causes the build to fail if any interface throws an exception not mapped in the configuration (see above) and does not document missing author tags. Note that warn is the default behaviour: issue types with this severity do not need to be added explicitly. We have added them in the code snippet above as a reference to all existing issue types.

Although this feature works in both the free and professional version of Miredot, only the professional version will document where exactly the violations in your code occur. The free version will limit its output to the number of violations detected.

Overview of Issue types

Below follows an overview of all issue types and their causes:

Issue type	Cause
JAVADOC_MISSING_SUMMARY	A method is not annotated with a summary.
JAVADOC_MISSING_INTERFACEDOCUMENTATION	A method is not documented with Javadoc comments.
JAVADOC_MISSING_PARAMETER_DOCUMENTATION	A parameter is not documented with Javadoc comments.
JAVADOC_MISSING_EXCEPTION_DOCUMENTATION	An exception is not documented with Javadoc comments.
JAVADOC_MISSING_AUTHORS	An interface is not annotated with an author.
JAXRS_MISSING_PATH_PARAM	A method has a parameter annotated with `@PathParam` that references a variable not found in the `@Path` value.
JAXRS_MISSING_PRODUCES	A method returns a body but misses an `@Produces` annotation.
JAXRS_MISSING_CONSUMES	An interface has a missing consumes definition, even though it has a response body.
REST_UNMAPPED_EXCEPTION	A method throws an exception that cannot be documented by Miredot. See status codes.
UNREACHABLE_RESOURCE	Two resources have the same path, causing one of them to be unreachable.
PARTIAL_RESOURCE_OVERLAP	A resource path matches the path of a different resource for certain values of its path variables, causing the resource to become unreachable.
INVALID_PATH	A resource path is malformed.
JSON_SCHEMA_TOO_LARGE	Overly large JSON payloads that can cause the generated HTML to have performance issues.