swagger-grails4

Table of Contents

• 1. Usage
  • 1.1. Requirements
  • 1.2. General Usage steps
    • 1.2.1. Specify gradle dependence
    • 1.2.2. Add @ApiDoc annotations
    • 1.2.3. API endpoint and html document URL
    • 1.2.4. More controls
      • 1.2.4.1. Advanced Response document
• 2. Features

Grails4 Plugin to automatically generate swagger/OpenAPI-v3 REST API documents.

Chinese README

1. Usage

1.1. Requirements

1. Grails v4 or greater

2. Java 1.8

3. Groovy 2.5

1.2. General Usage steps

1.2.1. Specify gradle dependence

repositories {
  maven { url "https://dl.bintray.com/bobyang/plugins" }
  // or jcenter()
}
dependencies {
  implementation 'swagger.grails4:swagger-grails4:0.0.1'
}

1.2.2. Add @ApiDoc annotations

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 {
}

Add @ApiDoc to action methods:

@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.

Add @ApiDoc annotation to the command class or domain classes.

@ApiDoc("The command contains User properties")
class UserCommand implements Validateable{
    /**
     * The name of user in comments.
     */
    String username
}

1.2.3. API endpoint and html document URL

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.

1.2.4. More controls

You can override comments using @ApiDoc in the fields

@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.

Using OpenAPI Parameter model to document parameters

@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.

1.2.4.1. Advanced Response document

You can change the properties of Response schema, this is convenient if your api response has payload that changed in action methods.

given response class like this:

@ApiDoc("A test rest api response class")
class RestApiResponse {
    /**
     * Error code
     */
    int code
    /**
     * Message
     */
    String msg
    /**
     * Return payload
     */
    Object info
}

override properties of a response class because this action return UserCommand in the info property

@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.

define schema in 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.

specify multiple "Status Code"

@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() {
}

specify multiple "MIME" content

@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() {
}

2. Features

• 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.

• 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'!