[Java] use JavaDoc to generate Swagger resource

Swagger 寫在注解讓整個代碼變得很複雜，所以找到有人寫在 JavaDoc 的方式，首先 Gradle 的設定如下：

// build.gradle
apply plugin: 'java'

configurations {
    doclet
}

dependencies {
    doclet (
        'com.tenxerconsulting:swagger-doclet:1.1.3',
        'javax.ws.rs:javax.ws.rs-api:2.1'
    )
}

task generateRestApiDocs(type: Javadoc) {
    source = sourceSets.main.allJava
    destinationDir = reporting.file('rest-api-docs')
    options.classpath = configurations.doclet.files.asType(List)
    options.docletpath = configurations.doclet.files.asType(List)
    options.doclet = 'com.tenxerconsulting.swagger.doclet.ServiceDoclet'
    options.addStringOption('apiVersion', '1')
    options.addStringOption('docBasePath', "/$project.name/static/swagger-ui")
    options.addStringOption('apiBasePath', "/$project.name")
    options.addBooleanOption('skipUiFiles', false)
}

public final class Hello {

    /**
     * Get user toggle.
     *
     * @param name your name
     * @return http response
     * @requiredParams name
     * @paramsDefaultValue name world
     * @responseType String
     * @responseMessage 200 ok `String
     * @responseMessage 500 internal error `javax.ws.rs.WebApplicationException
     */
    @GET
    @Path("/{name}")
    public Response getHello(@PathParam("name") String name) {
        return Response.Ok("Hello " + name).build();
    }
}

參考資料：

• GitHub: conorroche/swagger-doclet