I have a grails 2.4.5 application with the grails plugin swaggydoc. I'm able to get the UI with the documentation, however, the only way I'm able to have the POST, PUT and DELETE requests documentation automatically generated properly with the right url and Http method, is by overriding the RestFulController methods (save, update, and delete). If I don't do that, the method is considered a get request, even despite having the proper annotation. However, by doing that, the url names I put in UrlMappings.groovy gets overridden (except the GET requests) in the documentation and follows the default grails url naming behavior of controller/methodName, hence providing wrong urls for the documentation, so the documentation almost becomes useless, as not totally accurate.
pom.xml
...
<!-- API Documentation -->
<!-- Swagger-->
<dependency>
<groupId>com.github.rahulsom</groupId>
<artifactId>swaggydoc-commons</artifactId>
<version>0.28.0</version>
</dependency>
<dependency>
<groupId>org.grails.plugins</groupId>
<artifactId>swaggydoc</artifactId>
<version>0.9</version>
<type>zip</type>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2</artifactId>
<version>2.1.2</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2-servlet-initializer-v2</artifactId>
<version>2.1.2</version>
</dependency>
...
UrlMappings.groovy
class UrlMappings {
static mappings = {
"/$controller/$action?/$id?" {
constraints {
// apply constraints here
}
}
//api documentation
"/api/v1/docs"(controller: 'api')
//Events resource
group "/api/v1/events", {
"/$eventId?"(controller: 'event', action: 'getEvents', method: 'GET', parseRequest: true)
"/$eventId?/$recovery?"(controller: 'event', action: 'update', method: 'PUT', parseRequest: true)
"/$eventId?/$recovery?"(controller: 'event', action: 'save', method: 'POST', parseRequest: true)
}
}
Sample controller
@Secured(['IS_AUTHENTICATED_FULLY'])
@Api(
value = 'Events',
description = "Event APIs",
position = 1,
produces = 'application/json',
basePath = 'api/v1',
protocols = 'http, https'
)
class EventController extends RestfulController {
static responseFormats = ['json']
static scope = "singleton"
@Override
@ApiOperation(
value = "Update event",
httpMethod = 'PUT',
authorizations = @Authorization(value = 'oauth2')
)
@ApiResponses([
@ApiResponse(code = 204, message = 'No Content')
])
@ApiImplicitParams([
@ApiImplicitParam(name = 'Id', value = 'event id', paramType = 'path', dataType ='long')
])
def update() {
...
}
}
UrlMappings.groovy
class UrlMappings {
static mappings = {
"/$controller/$action?/$id?" {
constraints {
// apply constraints here
}
}
//api documentation
"/api/v1/docs"(controller: 'api')
//Events resource
group "/api/v1/events", {
"/$eventId?"(controller: 'event', action: 'getEvents', method: 'GET', parseRequest: true)
"/$eventId?/$recovery?"(controller: 'event', action: 'update', method: 'PUT', parseRequest: true)
"/$eventId?/$recovery?"(controller: 'event', action: 'save', method: 'POST', parseRequest: true)
}
}
I was expecting all the apis, as specified by the UrlMappings.groovy to not include any of the methods, however, Swaggydoc isn't even following my custom mapping. I was expecting at least:
- PUT /events/{eventId}
Is there a way to override this behavior, so I don't have to override the RestFulController Http methods (save, update and delete) and choose whatever method name I want and have the documentation urls being accurate?
At this point, I don't mind trying some other reliable plugin too, if that's not possible with the SwaggyDoc plugin.
The ideal scenario is to have the apis documentation automatically generated and have a ui that users can interact with and even pass a token to test the apis and get a response back.
Any feedback on how to do that with Grails 2.4.5 will be greatly appreciated.