raml-doc

Generate an HTML documentation of a RAML file. Send test requests to the service directly from within the documentation.

Usage as standalone tool

The documentation can be generated statically using the command line interface.

maven

Download raml-doc-standalone either manually or using maven, then execute

java -jar raml-doc-standalone.jar <raml-file>

npm

Install raml-doc from npm with sudo npm install raml-doc -g

Run it with raml-doc <raml-file>

Usage as a servlet

The documentation can also be generated from within a web application. Add this to web.xml

<servlet>
    <servlet-name>raml-doc</servlet-name>
    <servlet-class>guru.nidi.raml.doc.servlet.RamlDocServlet</servlet-class>
    <init-param>
        <param-name>ramlLocations</param-name>
        <param-value>classpath://api/myRaml.raml</param-value>
    </init-param>
</servlet>

<servlet-mapping>
    <servlet-name>raml-doc</servlet-name>
    <url-pattern>/api/*</url-pattern>
</servlet-mapping>

and the documentation is generated at startup and will be available directly from your application.

The available config parameters are the following:

Name | Meaning | Values -----|---------|------- ramlLocations | Comma separated list of RAML files. | Protocols like file://, classpath://, http:// are supported. features | Comma separated list of features to enable. | Features are: online: The RAML documentation is available through the application, download: The documentation provides a download link to the RAML file, tryout: The API can be tried out interactively from within the documentation, docson: Use Docson to display JSON schemas. baseUri | The URL the test requests should be sent to (overrides the baseUri setting in the RAML file). | baseUriParameters | Set the parameter values of the baseUri in the RAML file. | The format is parameter=value,.... Special values are $host and $path which are replaced by the actual host and path of the running servlet. customization | The location where the customized favicon.ico, custom-variables.less, custom-style.less should be loaded from. | For the supported protocols, see ramlLocations parameter. If not given, the first ramlLocation is used.

Another possibility is to subclass RamlDocServlet and override the configuration methods.

Resulting HTML

The resulting HTML supports the following:

• Select a method by using an anchor, e.g. res.html#get
• These query parameters:

Name | Meaning | Value -----|---------|------ expanded | Which resources in the resource tree on the left should be expanded. | Can be empty (all resources are expanded) or a comma separated list of resource names. u_* | A URI parameter value to predefine. | The value for the parameter. q_* | A query parameter value to predefine. | The value for the parameter. h_* | A header value to predefine. | The value for the header. f_* | A form parameter value to predefine. | The value for the parameter. method | Which method should be selected. (Same as anchor but without scolling.) | GET, POST, PUT, DELETE run | If a request of the selected method should be sent to the server. | none

Demo

Documentation of a subset of the GitHub API.