[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?