Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

restapidoc Build Status

This is a RESTful API documentation plugin for the Grails web application framework. Very much inspired by Swagger API documentation, this plugin reuses the available information of Grails Domain classes and Controllers to minimize documentation effort and to improve consistency. This approach aims to be a deeper and less narrative Grails integration than the original Swagger JAX-RS idea. It

  • is extending the Grails RestController
  • is using Grails HalRenderer
  • uses Annotations just for documentation purpose and not for semantic information
  • is as concise as possible
  • reuses already some basic annotations from Swagger but
  • it is not "Swagger compatible"
  • Grails 3.0 and above is not supported

Current Version 0.1.4

Grails restapidoc

Quick Start

  • it is recommended to use Grails >= 2.3.7. It is best tested with Grails 2.4.4. Please install it as required by Grails or use the grailsw wrapper.

  • EITHER Use the Binary by adding restapidoc it to your grails-app/conf/BuildConfig.groovy:

    compile ":restapidoc:0.1.4"
  • OR: Download this project by git clone e.g. to directory restapidoc.

    • cd restapidoc
    • to test it:
    grails test-app --echoOut
    • The project provides a Grails wrapper, so if you don't have Grails installed, run the tests with
    grailsw test-app --echoOut
    • Create a new Grails project parallel to restapidoc. Edit BuildConfig.groovy, add:
  • edit your spring/resources.groovy, add e.g. HalJsonRenderer:

	beans = {
		halPCollectionRenderer(HalJsonCollectionRenderer, Pet)
		halPRenderer(HalJsonRenderer, Pet)
  • add documentation to your Grails Domains e.g.:
	import restapidoc.annotations.ApiDescription
	import restapidoc.annotations.ApiProperty

	@ApiDescription(description = "Endangered Animals")
	class Pet {
		@ApiProperty(description = "Binomial name")
    	String name 
  • add documentation to your Grails Controller. If you want some generic Documentation for RestfulControllers, you can extend DocumentedRestfulController e.g. here PetController:
	import restapidoc.DocumentedRestfulController
	import restapidoc.annotations.ApiDescription

	@ApiDescription(description="Unrealistic shop for endangered animals")
	class PetController extends DocumentedRestfulController  {
		static responseFormats = ['hal','json']
		PetController() {

API Documentation

The following Annotations - similar like Swagger - are available:

  • ApiIgnore: element will be ignored in documentation
  • ApiDescription: used for Domain classes and Controller documentation
  • ApiProperty: domain property
  • ApiParam: paramter of a controller
  • ApiParams: a list of ApiParam
  • ApiOperation: controller operation
  • ApiResponse: controller operation response
  • ApiResponses: List of ApiResponse
  • DeleteMethod / GetMethod / PostMethod / PutMethod: marks controller operation as RESTful CRUD


  • 0.1.4 Grails 2.4.4 tested
  • 0.1.3 Grails 2.4.2 tested, issue#4 and issue#5, inherited domain attributes
  • 0.1.2 Grails 2.4.0 support
  • 0.1.1 publish binary version of this plugin
  • 0.1 initial version


Copyright (c) Siemens AG, 2013

This restapidoc plugin is licensed under the terms of the [Apache License, Version 2.0][Apache License, Version 2.0]. [Apache License, Version 2.0]:


A RESTful API documentation plugin for the Grails web application framework






No releases published


No packages published