Skip to content

Using the @Doc annotation

Jump to bottom
gsteinacker edited this page Mar 9, 2013 · 2 revisions

@Docs and @Doc

Links to human-readable documentation can be added to a json-home document using a docs hint (see json-home draft specification). This hint is generated, if you add a @Docannotation with a link attribute to the controller-class responsible for a link-relation type.

If you are planning to use the HtmlController to serve a HTML representation of your json-home document for developers, you possibly want to add some documentation to your link-relation types, var types, media types, and so on.

Using the @Doc annotation, you can:

  1. Add some short paragraphs to the description of a link-relation type.
  2. Link to external documentation.
  3. Link to local Markdown documents.

Links are added to the json-home as a docs hint and may be rendered into the HTML representation.

Examples

Adding a description

In order to associate a link-relation type with a description, you could use the @Doc annotation like this:

@Doc(rel = "/rel/products",
     value = {"The collection of products.",
              "This is a second paragraph, describing the collection of products."}
)
@Controller
public class ProductController {
...

The annotation must be provided at type level, because there may be multiple methods in the controller using the link-relation type /rel/products. The @Doc annotation is always referring to a link-relation using the relattribute.

The valueof the annotation may contain one or more Strings. Each String is rendered as a paragraph.

Links to documentation

You can add a link to some documentation instead of or in addition to the description provided with the value attribute:

@Doc(value = "A link to a single product.",
     rel = "/rel/product",
     link = "http://de.wikipedia.org/wiki/Produkt_(Wirtschaft)"
)

In this case, an absolute link is provided. You can also use a relative link; in this case, the link will be transformed into an absolute link by prepending the value of the property jsonhome.relationTypeBaseUri. See for details on how to use this.

The generated json-home of the link-relation type will contain a docs hint like this:

{ 
"resources" : {
   "http://specs.otto.de:8080/shop/rel/product" : {
      "href-template" : "http://example.org/shop/products/{productId}",
      "href-vars" : {
        "productId" : "http://specs.otto.de/shop/rel/product#productId"
      },
      "hints" : {
        "allow" : ["GET", "PUT"],
        "docs" : "http://de.wikipedia.org/wiki/Produkt_(Wirtschaft)",
        
        ...

Multiple @Docs

Many controllers will support more than one link-relation type. Because Java does not allow you to add one annotation multiple times to a type, we have to use the @Docs annotation to configure multiple @Doc like this:

@Controller
@RequestMapping(value = "/products")
@Docs({
        @Doc(value = {"The collection of products.",
                      "This is a second paragraph, describing the collection of products."},
             rel = "/rel/products"),
        @Doc(value = "A link to a single product.",
             rel = "/rel/product")
})
public class ProductsController {

In this example, documentation is provided for three link-relation types: the collection of products /rel/productsand a single product /rel/product.

Please note that only one @Doc per link-relation type is allowed. If your application contains multiple @Docannotations having the same rel attribute, only one value will be used by the generators.

Clone this wiki locally