解析 API Blueprint 文档并自动化生成代码（可定制模板）

时间 2019-11-17

标签解析 api blueprint 文档自动化生成代码定制模板栏目测试自动化繁體版

原文原文链接

最近大前端概念愈来愈火，本着学习的目的，写了一个自动化解析API Blueprint文档的模板代码生成工具，为了提升开发效率，本工具使用nodejs开发，vue.js做为可定制化的输出模板的辅助，本项目娱乐为主，但愿能给你们提供一些思路，扩展下技术栈javascript

源码地址

GitHub：github.com/free46000/A…html

下载与使用

普通方式

下载[APIBlueprintToGenerateCode]源码，须要注意源码使用ECMAScript6的语法
在源码目录下执行npm install命令，安装依赖包，本过程当中在会有一些安装 .NET Framework 2.0的相关错误提示，能够忽略
安装完成后在源码目录下执行node bin/www命令，启动服务器
在浏览器地址栏中输入http://localhost:3000便可访问页面，页面中能够自定义Api文档Git地址，若是Api文档没有上传Git，也能够把Api文档拷贝到页面输入框指定的路径下，能够自动识别，点击生成按钮，解析结果会展示在当前页面中

注意：源码中是过滤了以.apib结尾的文件列表，此处若是有须要能够联系做者，修改成传递参数控制前端

docker容器方式

因为代码定制化比较强，这里我会把DockerFile贴出来，你们有须要能够修改代码后自行build

效果截图

entities效果

apiset效果

主要流程

经过nodegit拉取API Blueprint文档到本地（固然这一步视你们的具体状况，也能够直接把Api文档拷贝到页面输入框指定的路径下）
经过drafter官方解析库解析API Blueprint文档，drafter解析后的结构并非太友好，这里须要写一些适配代码
解析Response中的json数据结构
借助vue.js生成html的模板代码
整合到docker容器

源码解析

API文档git下载

API Blueprint是一套基于markdown的API描述语言规范，基于此规范能够方便的生成mock接口，这样前端，移动端，后端能够并行开发，好处多多，但愿你们也多使用。 vue

nodegit地址
使用Git.Clone克隆API Blueprint文档
使用Repository.fetchAllfetch到最新文档
根据具体状况使用Repository.mergeBranches合并分支，源码中是把develop分支代码合并到master中，代码逻辑在git_handler.js中

解析API Blueprint

drafter地址
使用node的fs模块，读取文件列表，源码中是过滤了下以.apib结尾的文件列表，此处若是有须要能够联系做者，修改成传递参数控制
使用drafter.parse解析API Blueprint文档，解析后的格式为

{
  "element": "parseResult",
  "content": [
    {
      "element": "category",
      "meta": {
        "classes": [
          "api"
        ],
        "title": ""
      },
      "content": [
         {
          "element": "category",
          "meta": {
            "classes": [
              "resourceGroup"
            ],
            "title": ""
          },
          "content": [

        ... ...

}复制代码

能够发现上面的结构嵌套比较深，后面使用的时候会比较麻烦，这里把有效数据拿到，并为每一个HttpTransaction生成一个实体（JsonObject），处理逻辑在apib_parser.js中，解析以后的格式为：

[{
    href:'',//请求路径:/get/task/{taskid}
    hrefName:'',//路径对应name:GetTask
    title:'',//请求标题：获取任务
    hrefVariables:[ //路径对应Variable"content": "taskid"
        {"element": "String","content": "post_id"}
    ],
    subTitle:'',//请求标题：经过id获取任务
    tip:'',//相关提示
    method:'',//请求类型 POST or GET ...
    response:{},//响应实体{'taskId':1,'taskName':'任务'}
    param:{}//请求参数taskId
}]复制代码

咱们能够很方便的从上面拿到请求响应的数据，正常状况下会是json格式的，例如：{'taskId':1,'taskName':'任务'},
以上几步是在nodejs的服务端完成，通讯采用ajax，取得数据后咱们把HttpTransaction中请求响应的json数据转换为对生成实体类友好的结构，处理逻辑主要在to_bean.js中，处理以后的格式为：

[{
    className: className,//实体类中名字
    fields: [{ //实体类中含有的属性列表
        name: taskName, 
        type: String
    }],
    importTypes: [{//须要import的类型列表
        'java.util.List'
    }] 
}]复制代码

模板生成

通过以上的准备，获得了咱们须要的数据，而后借助vue.js渲染html代码模板,代码都在bean_template.html中，目前写了java实体类和Api接口类的模板，可自行扩展其余模板。下面贴出一段实体类的模板代码：

<div id="bean" v-if="beans">
    <div :id="bean.className" style="background: cornsilk">
        <p>package com.bean.response;</p>

        <p v-for="imp in bean.importTypes">import {{imp}};</p>

        <p>public class {{ bean.className }} {</p>
        <div v-for="field in bean.fields">
            private {{field.type}} {{field.name}};
        </div>
        <div v-for="field in bean.fields">
            public void set{{ firstToUpperCase(field.name) }}({{field.type}} {{ field.name }}) {<br>
            this.{{field.name}} = {{field.name}};<br>
            }<br><br>
            public {{field.type}} get{{ firstToUpperCase(field.name) }}() {<br>
            return this.{{field.name}};<br>
            }<br><br>
        </div>
        <p>}</p>
    </div>
</div>复制代码

docker整合

最后整合在docker容器中，docker可让应用程序布署在软件容器下的工做能够自动化进行，不过开发接触的偏少一些，有兴趣的能够了解一下，下面我贴出个人DockerFile代码：

# 选择image
FROM node:latest

# 建立源码目录并设置当前工做路径
RUN mkdir -p /usr/app
WORKDIR /usr/app

# 拷贝源码到目标路径
COPY ./bin /usr/app/bin
COPY ./public /usr/app/public
COPY ./routes /usr/app/routes
COPY ./views /usr/app/views
COPY ./app.js /usr/app/app.js
COPY ./package.json /usr/app/package.json

RUN npm install .

CMD [ "node", "/usr/app/bin/www" ]复制代码

总结

目前代码只是在html中进行输出，原本计划下一步在指定目录生成类文件，可是有两个问题没有办法很好解决，因此就暂时放弃了，一是实体类的命名；还有实体类去重，例如：任务列表和详情接口一样都会有任务的实体，自动化生成代码会生成两个类。 java

本项目主要是为了熟悉NodeJS vue等前端开发知识，娱乐为主，主要写写实现的思路，虽然写的比较简陋，可是里面用了一些比较好的开源组件API Blueprint nodegit docker 等，很是值得学习，欢迎留言交流，但愿能够帮助到你们。node

最后请容许打个小广告：做者开源了一个一个优雅的实现多类型的RecyclerView类库支持DataBinding Form表单录入，Github地址：github.com/free46000/M…git