Serving Markdown documents using DocController

DocController

The DocController (de.otto.jsonhome.controller.DocController) is used to serve Markdown documents as HTML pages. It is part of the jsonhome-spring module and currently not available in jsonhome-jersey.

Markdown is a nice format to provided users of your HTTP API with some documentation. In jsonhome you can use it to document your link-relation types, vendor-specific media types or other things.

Configuration

The DocController is listening to HTTP requests to /docs/**. It will look for Markdown documents under a root directory that is injected by Spring. The Spring configuration of the controller will look like this:

    <bean class="de.otto.jsonhome.controller.DocController">
        <property name="rootDir" value="classpath:/docs/*" />
    </bean>

In order to add some documentation, we will have to add a file to our project: /src/main/resources/docs/rel/storefront.md The file must contain Markdown format as described in markdown4j.

Using DocController to serve @Doc links

The @Doc annotation can be used to provide some information about a link-relation type. This may look like this:

@Controller
@RequestMapping(value = "/storefront")
@Rel("/rel/storefront")
@Doc(rel = "/rel/storefront",
     link = "docs/rel/storefront.md"
)
public class StorefrontController {

    @RequestMapping(produces = "text/html")
    public String getStorefront() {
        return "storefront";
    }

}

The link attribute of the @Doc may either contain an absolute URI to an external documentation, or (as in the example) a relative URI.

Relative links will be prefixed with the value of the property jsonhome.relationTypeBaseUri. In case of the shop example, this property is configured as http://localhost:8081/shop. Therefore, the absolute link to the documentation of the link-relation type /rel/storefrontwill be http://localhost:8081/shop/docs/rel/storefront.md.

If you want to see this in a working example, please have a look at the example/shop sources.