Generate an HTML documentation of a RAML file. Send test requests to the service directly from within the documentation.
The documentation can be generated statically using the command line interface.
Download raml-doc-standalone either manually or using maven, then execute
java -jar raml-doc-standalone.jar <raml-file>
Install raml-doc from npm with sudo npm install raml-doc -g
Run it with raml-doc <raml-file>
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.
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 |
Documentation of a subset of the GitHub API.