[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

[Java] Swagger3 + JAX-RS Jersey

首先加入依賴包 swagger-jersey2-jaxrs，

// build.gradle
dependencies {
    compile 'io.swagger:swagger-jersey2-jaxrs:1.5.20'
}

然後註冊 swagger，

// src/main/java/demo/WebApplication.java
package demo;

import javax.ws.rs.ApplicationPath;
import org.glassfish.jersey.server.ResourceConfig;

@ApplicationPath("/")
public class WebApplication extends ResourceConfig {
    public WebApplication() {
        packages("<MY-PACKAGE>"); // "demo"

        register(io.swagger.jaxrs.listing.ApiListingResource.class);
        register(io.swagger.jaxrs.listing.SwaggerSerializers.class);
    }
}

接著寫 swagger annotation，

// src/main/java/demo/Hello.java
package demo;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@Api(value="Hello World API")
@Path("/hello")
public class Hello {
    @ApiOperation(value = "say hello", response = String.class)
    @GET()
    public String hello() {
        return "hello";
    }
}

然後打開 url: http://localhost:8080/<PROJECT>/hello/swagger.json 確認是否正常。

沒問題之後，下載 Swagger UI dist 檔案到 src/main/webapp/static/， 將 index.html 裡面的 url https://petstore.swagger.io/v2/swagger.json 修改成剛剛的 http://localhost:8080/<PROJECT>/hello/swagger.json。

並且修改 web.xml 使可以讀取 Swagger UI，

// src/main/webapp/WEB-INF/web.xml
<web-app ...>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>/static/*</url-pattern>
    </servlet-mapping>
</web-app>

然後就可以使用 http://localhost:8080/<PROJECT>/static/index.html。

參考資料：

• GitHub: swagger-api/swagger-core - Swagger Core Jersey 2.X Project Setup 1.5
• iCanCode: Configuring Swagger with Jersey
• GitHub: swagger-api/swagger-ui

2019/07/12 更新：
附註：StackOverflow: What exactly is the ResourceConfig class in Jersey 2?