Grails4 Plugin to automatically generate swagger/OpenAPI-v3 REST API documents.
repositories {
maven { url "https://dl.bintray.com/bobyang/plugins" }
// or jcenter()
}
dependencies {
implementation 'swagger.grails4:swagger-grails4:0.0.1'
}Add @ApiDoc annotations to Controller and Command/Domain classes any Schema classes you want plugin to automatically extract your comments as OpenAPI descriptions.
Add @ApiDoc to controller:
@ApiDoc(tag = {
description "User API"
})
class UserController {
}@ApiDoc(operation = {
summary "Create User"
description "Create a new user"
responses "200": {
content "default": {
description "success response"
schema MyApiResponse
}
}
})
def createUser(UserCommand command) {
}The plugin will automatically extract comments or annotation in the command class, if you add @ApiDoc annotation to the class.
@ApiDoc("The command contains User properties")
class UserCommand implements Validateable{
/**
* The name of user in comments.
*/
String username
}Now start your REST api grails application and visit "http://<host:port>/api", you can see swagger-ui document.
Visit "http://<host:port>/api/doc", you can get json object of document.
@ApiDoc("The command contains User properties")
class UserCommand implements Validateable{
/**
* The name of user in comments.
*/
@ApiDoc("The name of user")
String username
}If the action parameters is primitive types, you can document them like this.
@ApiDoc(operation = {
summary "Login"
description "Login with user name and password"
parameters([{
name "username"
description "User Name"
inType "query"
schema { type "string" }
}, {
name "password"
description "Password"
inType "query"
schema { type "string" }
}])
})
def login(String password, String username) {
}Every parameter in the 'annotation closure' (Groovy concept) is a Parameter object, so you can use any 'primitive type properties' that Parameter object has, complex object properties needs special processing, maybe not available.
You can change the properties of Response schema, this is convenient if your api response has payload that changed in action methods.
@ApiDoc("A test rest api response class")
class RestApiResponse {
/**
* Error code
*/
int code
/**
* Message
*/
String msg
/**
* Return payload
*/
Object info
}@ApiDoc(operation = {
summary "Login"
description "Login with user name and password"
responses "200": {
content "default": {
description "success response"
schema RestApiResponse, properties: [info: UserCommand]
}
}
})
def login(LoginCommand loginCommand) {
}You can even totally define schema in the annotation closure.
@ApiDoc(operation = {
summary "Create User"
description "Create a new user"
responses "200": {
content "default": {
description "success response"
schema {
name "CustomSchema"
type "string"
description "The customized json response"
}
}
}
})
def createUser(UserCommand command) {
}You can specify multiple "Status Code" and content MIME in responses.
@ApiDoc(operation = {
summary "List Users"
description "List users, support query and paging parameters"
responses "200": {
content "default": {
description "success response"
schema RestApiResponse
}
}, "201": {
content "default": {
description "success response with 201"
schema UserCommand
}
}
})
def index() {
}@ApiDoc(operation = {
summary "List Users"
description "List users, support query and paging parameters"
responses "200": {
content "default": {
description "success response"
schema RestApiResponse
}, "text/xml": {
description "success response with 201"
schema UserCommand
}
}
})
def index() {
}-
Automatically build operations from grails controllers and UrlMapping.
-
Automatically extract Schema from any classes with @ApiDoc annotation.
-
Automatically extract comments of fields to build descriptions of properties.
-
Automatically create description of values of Enum, if there is an id property then show id value in descriptions.
-
Automatically create element Schema of array.
-
Correctly process reference cycle Because swagger-ui will hang-up if there is a cycle referencing in schemas, so we will not reference existed schema in array schemas items.
-
Hide api doc in production environment.
-
Automatically generate response object document.
-
'properties' of response Schema can be customized
-
TODO: Can handle inherited trait properties and plain class properties.
-
TODO: recognize GORM association properties.
If you need some more features please feel free to submit an issue with 'enhancement' label, any suggestions are welcome.
We wish this plugin can save your time to write tedious api documentations.
Enjoy Grails REST API document with 'swagger-grails4'!
We are Beijing Telecwin Co.Ltd. a company provides software develop services and develop SaaS systems for e-commercial merchants in PWA such as weixin mini-programs and Mobile-Application such as Android/iOS app.
We located in Beijing China, if you are interested in our service and products please feel free to contact us in [email protected].
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent