HTTP Status Codes

Miredot can automatically document the response of an endpoint based on the return type used by the java method that implements your endpoint. In many cases, Miredot cannot automatically derive the status code of a response. Therefore, you will need to provide additional configuration.

In order to document the status codes of the REST endpoints, Miredot combines three types of resources:

1. Globally configured status codes are added to all endpoints. For example, you can choose to document "500 - Internal Server Error" for all your resources. You can optionally limit these kinds of globally configured status codes to one or more HTTP methods. For example: only document "412 - Precondition failed" on all PUT and POST endpoints. See below for documentation.

2. Status codes tied to exceptions thrown by the method that represents your REST endpoint. For example, you may wish to specify that you want a "404 - Not Found" documented whenever a method throws a NotFoundException. You can also specify those status codes in your pom.xml or gradle.build file.
   For Spring-MVC projects, we support the @ResponseStatus annotation. This annotation is placed on top of an exception class and specifies how that exception is mapped to a status code. If you do this, you don't need to provide additional Miredot configuration. No equivalent is currently available for JAX-RS.
   The descriptive message from a status code caused by an exception is that of the Javadoc documenting the exception if available. Miredot uses the message from the configuration or @ResponseStatus annotation as a fallback.
   See below for documentation.

3. Method-specific status codes. You can add the documentation of a status code using a Javadoc @statuscode tag.

Combining all this information may result in the same status code being documented multiple times. This is intentional since the same status code may be returned for several reasons, and you want to document each one of those reasons.

Miredot will always document status codes documented with @statuscode and status codes tied to exceptions. Globally configured status codes are only added if it is not already documented using @statuscode or an exception. You can force Miredot to add that status code by marking it sticky. This allows you to specify global defaults which you can override at the REST endpoint level.

Finally, Miredot will deduplicate: regardless of origin, the same status code will never be documented twice on the same REST endpoint if they have the same descriptive message.

Configuration of Status Codes

To map a status code, simply add an httpStatusCodes block to your configuration. This block may contain any number of httpStatusCode entries, each containing

• httpCode: which status code to document
• document: when to document it
• defaultMessage: a default message to use if no other documentation is present in the code
• sticky: to enforce including the globally configured status code (default: false).

The document property can contain one of these values:

• "always": the httpCode with the default documentation is added to every interface. This is convenient if you wish to specify, for example, that every interface can return a 500 - Internal Server Error.
• "comma-seperated list of http methods": e.g. put, post. This is a great option if you want to specify for each method that an invalid JSON results in a 412 - Precondition Failed. Since only http put and post methods receive input, only those interfaces need to document this status code.
• "explicit: fully qualified exception name": The status code is documented whenever the exception is thrown.

An example clarifies a lot:

Maven

<configuration>
    <restModel>
        <httpStatusCodes>
            <httpStatusCode>
                <httpCode>200</httpCode>
                <document>always</document>
                <defaultMessage>The service call has completed successfully.</defaultMessage>
            </httpStatusCode>
            <httpStatusCode>
                <httpCode>401</httpCode>
                <document>explicit: com.acme.exceptions.AuthorizationException</document>
                <defaultMessage>The user is not authorized to use this service.</defaultMessage>
            </httpStatusCode>
            <httpStatusCode>
                <httpCode>412</httpCode>
                <document>put,post</document>
                <defaultMessage>Invalid JSON/XML input.</defaultMessage>
            </httpStatusCode>
            <httpStatusCode>
                <httpCode>500</httpCode>
                <document>always</document>
                <defaultMessage>The service call has not succeeded.</defaultMessage>
                <sticky>true</sticky> <!-- Document always, even if there is an @statuscode tag -->
            </httpStatusCode>
        </httpStatusCodes>
    </restModel>
</configuration>

Gradle

If you want to map multiple exceptions to the same statuscode, add "-<id>". The example below maps multiple exceptions to the 401 statuscode.

miredot {
    restModel {
        httpStatusCodes {
            '200' { 
                document = 'always'
                defaultMessage = 'The service call has completed successfully.' 
            }
            '401' {
                document = 'explicit: com.qmino.miredot.petstore.exceptions.AuthorizationException'
                defaultMessage = 'The user is logged in, but is not authorized to use this service.'
            },
            '401-1' {
                document = 'explicit: com.qmino.miredot.petstore.exceptions.AnotherException'
                defaultMessage = 'Something bad happened.'
            }
            '412' { 
                document = 'put,post'
                defaultMessage = 'Invalid JSON/XML input.' 
            }
            '500' { 
                document = 'always'
                defaultMessage = 'Internal server exception. The service call did not succeed.'
                sticky = true // Document always, even if there is an @statuscode tag
            }
        }
    }
}