组件说明
前后端分离的开发模式，REST APIs 需要在线查看接口文档及调试API，比如使用Postman等，那么Java后台就需要一种生成API接口文档的工具或方式，研究市面上的一些文档生成方式，要么较为复杂、要么非V7 的nutz 技术体系，于是构想自己独立实现一套注解，来实现API 文档的生成和在线调试功能。
在开发 Swagger V3(OpenAPI) 标准文档格式生成的同时，突然想到复用这套注解，扩展几个属性，就可以实现后台表单验证功能，好像发现了新大陆，一套注解，可以解决两个比较常用且重要的功能，想法不错，能不能实现呢？
注解定义
OpenAPI 一套注解我是定义在 wk-starter-common里的，主要考虑其是公共的可复用的：
- @ApiDefinition
控制类注解,定义被解析的控制类,以及接口标签名 - @ApiOperation
Http请求方法注解,需配合 @GET @POST @DELETE 注解使用 - @ApiFormParams
表单对象注解,定义form参数的字段名称、实体类等 - @ApiImplicitParams
请求参数注解,定义 Query/Path/Cookies 等参数 - @ApiResponses
响应对象注解,自动拼接为 Result.data,定义响应结果 - @ApiModel
实体类注解,定义被解析的实体类
其中，
- @ApiFormParam
表单参数注解 - @ApiImplicitParam
查询参数注解 - @ApiModelProperty
实体类属性注解
他们有几个公共的属性字段，如 required=是否必填、example=文档调试示例值、df=默认值、check=是否进行值验证、validation=值验证正则、regex=自定义正则、msg=值验证失败提示文字 等，较为容易理解。
解析并生成文档
NutzReader 这个类是关键，读取注解并进行解析，然后组装成 OpenAPI 文档格式，主要参考如下资源：
- https://swagger.io/specification/ 规范说明
- https://swagger.io/docs/specification/about/ 规范说明
- https://github.com/swagger-api/swagger-core/tree/master/modules Swagger-core 源码
- https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/Reader.java 解析类源码
解析后，利用 HttpServlet 生成Json或Yaml格式数据输出即可：
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
final String pathInfo = req.getRequestURI();
if (pathInfo.endsWith("/openapi.json") || pathInfo.endsWith("/openapi.yaml")) {
OpenAPI oas = (OpenAPI) req.getServletContext().getAttribute("openapi");
String type = "json";
String acceptHeader = req.getHeader("Accept");
if (Strings.isNotBlank(acceptHeader) && acceptHeader.toLowerCase().contains("application/yaml")) {
type = "yaml";
} else if (req.getRequestURL().toString().toLowerCase().endsWith("yaml")) {
type = "yaml";
}
resp.setStatus(200);
PrintWriter pw;
if (type.equalsIgnoreCase("yaml")) {
resp.setContentType("application/yaml");
pw = resp.getWriter();
pw.write(io.swagger.v3.core.util.Yaml.pretty(oas));
pw.close();
} else {
resp.setContentType("application/json");
pw = resp.getWriter();
pw.write(io.swagger.v3.core.util.Json.pretty(oas));
pw.close();
}
} else {
resp.setStatus(404);
}
}
预览与在线调试
API文档查看器源码在我另外一个开源项目里 budwk-openapi-viewer ，不再赘述，主要是对Json数据对解析和展示。
那么最终效果如何呢，可以点击 这里 查看，或登录 https://demo.budwk.com 查看。
