stoicflame/enunciate — pull request #24 by MnlK (2013-07-30 07:24:56+00:00)
Title: Some new features

Enunciate was lacking some features that prevented me from using it, so I added them ;) I tried to keep the features optional.

Custom Resource Labels
------------------------------------
The labels for REST methods are created from the path of the resource. With long paths, they become unreadable.
I created a new annotation to be able to provide a custom label for a method.
If it isn't used, the default path-style is used.

Example:

```
@ResourceLabel(value = "createInitialAccount")
```

Additional Response Headers
------------------------------------------
To document additional response headers in a comfortable way, I enhanced the @ResponseCode annotation with an array of additional headers.
They will be displayed in new columns in the "Status Codes" table. There may be as many headers as wanted (or none).

Example:

```
@StatusCodes({
@ResponseCode(code = 400, condition = "Missing or empty mandatory attribute: attributeXyz", additionalHeaders = {
@ResponseHeader(name = "ENHANCED_STATUS", description = "MISSING_ATTRIBUTE(attributeXyz)")})
})
```

Additionally I have added a method that extends the common http status codes to a string with the number + description of the code (e.g 200 -> "200 OK").

Sample Request / Response
-----------------------------------------
I've added two annotations that will create a sample Http Request or Response in the documentation. I think sometimes it's nice to have. (@SampleRequest, @SampleResponse)

Example:
@SampleRequest might generate something like this under the "Request Body" section:

```
POST .../rest/Account/alloc/blank
Accept: application/xml;application/json
Content-Type: application/json
--- Body ---
{ "accountType" : "..." }
```

Last I added a parameter to the enunciate.xml tag. It allows to hide a file from the download page. I did this, because I wanted a possibility to add a html file with additional info, that I can link from the documentation, but should not be shown on the download page. At least i haven't found another way to do this.

Example:

```

```