BudWk V7 builds a microservice development framework from scratch - 06 Interface document generation component

Component Description

In the development model with the front-end and back-end separation, REST APIs need to view interface documents and debug APIs online, such as using Postman, etc., then the Java backend needs a tool or method to generate API interface documents, study some document generation methods on the market, or relatively The complex or non-V7 nutz technical system, so I conceived of independently implementing a set of annotations to realize the API document generation and online debugging functions.

While developing the Swagger V3 (OpenAPI) standard document format generation, I suddenly thought of reusing this set of annotations and extending a few attributes to realize the background form verification function. It seems that a new world has been discovered. A set of annotations can solve two commonly used And the important function, the idea is good, can it be realized?

Annotation Definition

I defined a set of annotations for OpenAPI in wk-starter-common , mainly considering that it is public and reusable:

@ApiDefinition控制类注解,定义被解析的控制类,以及接口标签名
@ApiOperationHttp请求方法注解,需配合 @GET @POST @DELETE 注解使用
@ApiFormParams表单对象注解,定义form参数的字段名称、实体类等
@ApiImplicitParams请求参数注解,定义 Query/Path/Cookies 等参数
@ApiResponses响应对象注解,自动拼接为 Result.data,定义响应结果
@ApiModel实体类注解,定义被解析的实体类

in,

@ApiFormParam表单参数注解
@ApiImplicitParam查询参数注解
@ApiModelProperty实体类属性注解

They have several common property fields, such as required=是否必填、example=文档调试示例值、df=默认值、check=是否进行值验证、validation=值验证正则、regex=自定义正则、msg=值验证失败提示文字etc. , which are easier to understand.

Parse and generate documentation

The NutzReader class is the key. It reads the annotations and parses them, and then assembles them into the OpenAPI document format. Mainly refer to the following resources:

https://swagger.io/specification/specification _
https://swagger.io/docs/specification/about/specification _
https://github.com/swagger-api/swagger-core/tree/master/modules Swagger-core source code
https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/Reader.java parsing class source code

After parsing, use HttpServlet to generate data output in Json or Yaml format:

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);
        }
    }

Preview and online debugging

The source code of the API document viewer is in budwk-openapi-viewer , another open source project of mine, so I won't go into details. It mainly parses and displays the Json data pair.

So what is the final effect, you can click here to check, or log in to https://demo.budwk.com to check.