Skip to content
A RESTful API documentation plugin for the Grails web application framework
Groovy CSS Java Batchfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
grails-app
src
test/unit/restapidoc
web-app
wrapper
.gitignore
.travis.yml
README.md
RestapidocGrailsPlugin.groovy
application.properties
grailsw
grailsw.bat
screenshot1.png

README.md

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:
    grails.plugin.location.'restapidoc'="../restapidoc"
    
  • edit your spring/resources.groovy, add e.g. HalJsonRenderer:

	import grails.rest.render.hal.HalJsonCollectionRenderer
	import grails.rest.render.hal.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() {
			super(Pet)
		}
	}

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

History

  • 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

License

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]: http://www.apache.org/licenses/LICENSE-2.0.html

You can’t perform that action at this time.