nutz 集成swagger rest接口文檔

今天嘗試nutz集成 swagger rest接口文檔

按照以下步驟集成

一、增加依賴

• maven依賴

<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-core</artifactId>
	<version>1.5.16</version>
</dependency>
<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-servlet</artifactId>
	<version>1.5.16</version>
</dependency>

• 傳統web項目下載本文資源(下載)jar包放到lib目錄下

二、添加SwaggerModule

@IocBean(create = "init")
@At("/swagger")
public class SwaggerModule {

    private static final Log log = Logs.get();

    protected Swagger swagger;

    @Ok("void")
    @At
    public void swagger(HttpServletRequest request, HttpServletResponse response) throws Exception {
        if ("true".equals(request.getParameter("force")))
            init(); //強制刷新
        final String pathInfo = request.getRequestURI();
        if (pathInfo.endsWith("/swagger.json")) {
            response.setContentType("application/json");
            response.getWriter().println(Json.mapper().writeValueAsString(swagger));
        } else if (pathInfo.endsWith("/swagger.yaml")) {
            response.setContentType("application/yaml");
            response.getWriter().println(Yaml.mapper().writeValueAsString(swagger));
        } else {
            response.setStatus(404);
        }
    }
    
	@At("/")
    @Ok("->:/swagger/index.html")
    public void index() {}

    public void init() {
        log.info("init swagger ...");
        swagger = new Swagger();
        Info info = new Info();
        info.title("ABC....");
        swagger.info(info);
        HashSet<Class<?>> classes = new HashSet<>();
        // 把下來的package路徑改成你自己的package路徑
        for (Class<?> klass : Scans.me().scanPackage("net.wendal.nutzbook.swagger")) {
            classes.add(klass);
        }
        Reader.read(swagger, classes);
    }
}

三、添加swagger-ui

在src/main/webapp(maven項目)或者WebContent(Eclipse普通JavaEE項目)下,建一個swagger目錄

從 https://github.com/swagger-api/swagger-ui/releases 下載最新,取裏面dst目錄

將dst目錄裏面的文件統統放入swagger目錄,效果如下

- src
	- main
		- webapp
			- swagger
				- index.html
				- swagger-ui.js
				- ...

然後修改index.html裏面的

url: "http://petstore.swagger.io/v2/swagger.json",
// 改成
url: "(當前項目的路徑)/swagger/swagger.json",

四、添加swagger註解

@Api(value = "demo")
@IocBean
@At("/demo")
public class SwaggerDemoModule {

    @GET
    @ApiOperation(value = "心跳接口", notes = "發我一個ping,回你一個pong", httpMethod="GET")
    @At
    @Ok("json:full")
    public Object ping() {
        return new NutMap("ok", true).setv("data", "pong");
    }

    @POST
    @ApiOperation(value = "回顯接口", notes = "發我一個字符串,原樣回覆一個字符串", httpMethod="POST")
    @ApiImplicitParams({@ApiImplicitParam(name = "text", paramType="form", value = "想發啥就發啥", dataType="string", required = true)})
    @At
    @Ok("raw")
    public String echo(@Param("text") String text) {
        return text;
    }
}

訪問 http://localhost:8080/swagger/ 即可看到swagger的界面

本文參考