|
|
|
This feature generates online documentation. This documentation is available in two versions.
|
|
|
|
|
|
|
|
* /_api: A list of all registered handlers and the methods provided by them. Special annotations
|
|
|
|
can be used to augment/modify method descriptions.
|
|
|
|
* `@Documentation`: prints an extra comment in front of the method signature.
|
|
|
|
* more?
|
|
|
|
* /_help: Prints an overview how to use the configured RequestHandler and the registered features.
|
|
|
|
Also includes the API-section.
|
|
|
|
|
|
|
|
Documentation accepts content negotiation, i.e., by adding a `.txt` or setting the HTTP header `Accept: text/plain`
|
|
|
|
you can force a plain text description.
|
|
|
|
This, for example, makes the API description machine-readable.
|
|
|
|
|
|
|
|
## Maven
|
|
|
|
|
|
|
|
<dependency>
|
|
|
|
<groupId>dfki.sds.delight</groupId>
|
|
|
|
<artifactId>docu-delight-feature</artifactId>
|
|
|
|
<version>4.0-SNAPSHOT</version>
|
|
|
|
</depencency> |
|
|
|
This is a feature creating online-documentation for the running json-over-http delight instance.
|
|
|
|
|
|
|
|
### General Help Page
|
|
|
|
|
|
|
|
${ROOT_URL}/_help{.txt,.html}
|
|
|
|
|
|
|
|
This prints out a summary of things that are supported by the Delight backend. It also prints a summary
|
|
|
|
of all enabled features and all available service methods.
|
|
|
|
You can force a plain text version by adding .txt (or by setting `Accept: text/plain`)
|
|
|
|
|
|
|
|
### API documentation
|
|
|
|
|
|
|
|
${ROOT_URL}/_api{.txt,.html}
|
|
|
|
|
|
|
|
Prints out a summary of registered handlers and their provided methods.
|
|
|
|
Force a text version by adding .txt (or by setting Accept: text/plain).
|
|
|
|
The text version can serve as machine readable versions used by clients to use/enable the existing API.
|
|
|
|
|
|
|
|
Add a `@Documentation` annotation to have an additional description displayed for a method.
|
|
|
|
|
|
|
|
An example method description includes the path to the handler method, a possible empty list of parameters along with their names and types, the return type
|
|
|
|
and an additional description added through the `@Documentation` annotation. The use of `@Polymorph` annotations are also displayed.
|
|
|
|
A description might look like this:
|
|
|
|
|
|
|
|
Description provided by @Documentation annotation
|
|
|
|
${ROOT_URL}/myHandler/bounceBeanList?parameterP1=java.util.List<de.dfki.delight.example.TestPojo>(polymorph)⇒java.util.List<de.dfki.delight.example.TestPojo>
|
|
|
|
|
|
|
|
### Context Variables
|
|
|
|
|
|
|
|
The following context variables can be used in description templates (`description.md`). Some of the variables
|
|
|
|
are populated from build environment and are rather static. Other variables are derived from
|
|
|
|
the runtime environment and are therefore rather dynamic.
|
|
|
|
|
|
|
|
* (runtime) ROOT_URL
|
|
|
|
* (runtime) ROOT_PATH
|
|
|
|
* (runtime) HOST
|
|
|
|
* (runtime) PORT
|
|
|
|
* (build) DELIGHT_GROUPID
|
|
|
|
* (build) DELIGHT_VERSION
|
|
|
|
|
|
|
|
### Maven
|
|
|
|
|
|
|
|
<dependency>
|
|
|
|
<groupId>dfki.sds.delight</groupId>
|
|
|
|
<artifactId>docu-delight-feature</artifactId>
|
|
|
|
<version>4.0-SNAPSHOT</version>
|
|
|
|
</depencency>
|
|
|
|
|
|
|
\ No newline at end of file |
