一种基于接口文档的代码自动生成方法

技术领域

本发明涉及文档代码领域，尤其涉及一种基于接口文档的代码自动生成方法。

背景技术

目前流行的接口文档自动生成普遍有三种方式：一种使用japidocs，这是一种最简单也最高效的快速生成接口文档的方式，也是对既有项目改造代价最小的方式，可用于生成springboot api文档；一种使用Swagger后可以直接通过代码生成文档，同时Swagger生成的文档还支持在线测试；还有一种使用开源的接口文档生成工具，该类工具通常需要单独安装使用。

目前，接口文档要么是研发人员编写后再根据接口文档编写代码，要么是编写代码后再通过插件或者工具生成接口文档，存在以下问题：

研发人员先编写接口文档再编写接口代码，这种方式接口文档编写后无法直接生成接口代码，需要研发人员根据文档开发接口代码，这种方式增加了研发工作量，也容易存在接口代码与接口文档不一致情况；

研发人员先编写接口代码再通过插件或者工具生成接口文档，这种方式实际并不规范，标准规范是先编辑接口文档再进行代码研发，这种情况导致后端代码开发完成后，前端或者关联系统才可以拿到接口文档进行研发，增加了研发周期，若前端或者关联系统不等接口文档与后台代码同步研发，这种情况易导致前端、关联系统与后端代码接口不一致，导致返工的情况。

发明内容

鉴于上述问题，提出了本发明以便提供克服上述问题或者至少部分地解决上述问题的一种基于接口文档的代码自动生成方法。

根据本发明的一个方面，提供了一种基于接口文档的代码自动生成方法，所述生成方法包括：

定义接口模板；

通过开发工具实现所述接口模板的插件，生成接口文档；

根据所述生成接口文档选择相应文档进行接口代码生成，获得生成代码；

根据所述生成代码发布插件。

可选的，所述定义接口模板具体包括：

定义设计一版标准的接口模板，包括：接口名称、接口路径、请求方式、请求数据类型、响应数据类型、状态、接口描述、请求参数、返回参数要素。

可选的，所述请求参数包括：英文名称、中文名称、数据类型、长度、是否必输、备注；所述返回参数包括：英文名称、中文名称、数据类型、长度、是否必输、备注。

可选的，所述通过开发工具实现所述接口模板的插件，生成接口文档具体包括：

使用IntelliJ IDEA开发插件，配置IntelliJ Platform Plugin SDK、创建一个插件项目、启用Plugin DevKit、创建action动作、编写action；

通过插件action实现标准的接口模板页面，页面要素包括标准接口模板要素；

通过插件做的接口模板页面，录入相关接口信息。

可选的，所述根据所述生成接口文档选择相应文档进行接口代码生成具体包括：定义选择接口文件；实现接口文件生成代码。

可选的，所述定义选择接口文件具体包括：

采用插件action开发实现右键选择上面方法生成的接口文档，实现读取文件所在文件夹下文件列表进行多选操作，选择完成后，进行编译功能按钮，按钮携带选择的文件列表作为特定参数。

可选的，所述实现接口文件生成代码具体包括：

通过注解处理器自定义一个编译期注解，所述注解实现为，代码进行编译时，读取上面携带的参数，所述参数为接口文档文件列表名，使用反射机制实现读取该接口文档列表参数进行遍历处理，同时开发控制层、业务层、PO层的代码模板，其中关键代码数据由参数替换，遍历解析文件要素和请求返回参数后可套入代码模板，实现了以Java代码作为输入，生成文件作为输出。

可选的，所述根据所述生成代码发布插件具体包括：

自定义插件提交到Marketplace，注册Jetbrains账号，选择插件文件，选择License以及标签，点击Upload上传至Marketplace，系统审核后就能在Marketplace中搜索到插件下载使用了。

本发明提供的一种基于接口文档的代码自动生成方法，所述生成方法包括：定义接口模板；通过开发工具实现所述接口模板的插件，生成接口文档；根据所述生成接口文档选择相应文档进行接口代码生成，获得生成代码；根据所述生成代码发布插件。解决研发人员编写接口文档后再参照接口文档手动编写接口代码导致与接口文档不一致问题。

上述说明仅是本发明技术方案的概述，为了能够更清楚了解本发明的技术手段，而可依照说明书的内容予以实施，并且为了让本发明的上述和其它目的、特征和优点能够更明显易懂，以下特举本发明的具体实施方式。

附图说明

为了更清楚地说明本发明实施例的技术方案，下面将对实施例描述中所需要使用的附图作简单地介绍，显而易见地，下面描述中的附图仅仅是本发明的一些实施例，对于本领域普通技术人员来讲，在不付出创造性劳动的前提下，还可以根据这些附图获得其它的附图。

图1为本发明实施例提供的一种基于接口文档的代码自动生成方法的流程图；

图2为本发明实施例提供的插件页面原型示意图。

具体实施方式

下面将参照附图更详细地描述本公开的示例性实施例。虽然附图中显示了本公开的示例性实施例，然而应当理解，可以以各种形式实现本公开而不应被这里阐述的实施例所限制。相反，提供这些实施例是为了能够更透彻地理解本公开，并且能够将本公开的范围完整的传达给本领域的技术人员。

本发明的说明书实施例和权利要求书及附图中的术语“包括”和“具有”以及他们的任何变形，意图在于覆盖不排他的包含，例如，包含了一系列步骤或单元。

下面结合附图和实施例，对本发明的技术方案做进一步的详细描述。

如图1所示，一种基于接口文档自动生成代码的方法，包含以下模块：

接口文档生成：接口文档编辑，用于定义代码的标准接口，其特征在于，所述接口文档把生成文件放在SpringBoot项目下的classpath中，所述classpath是SpringBoot资源文件的存放位置；

代码自动生成：基于自定义注解原理自动生成代码开发的，所述代码自动生成是依据注解处理器，所述注解处理器，以Java代码(或者编译过的字节码)作为输入，生成文件(通常是.java文件)作为输出。

一种基于接口文档自动生成代码的方法，包含以下步骤：

一：定义接口模板

定义设计一版标准的接口模板，包含接口名称、接口路径、请求方式、请求数据类型、响应数据类型、状态、接口描述、请求参数、返回参数要素；

请求参数：英文名称、中文名称、数据类型、长度、是否必输、备注

返回参数：英文名称、中文名称、数据类型、长度、是否必输、备注

二：通过开发工具实现接口模板插件

使用IntelliJ IDEA开发插件，配置IntelliJ Platform Plugin SDK、创建一个插件项目、启用Plugin DevKit、创建action动作、编写action；

通过插件action实现标准的接口模板页面，页面要素包含上述标准接口模板要素。插件页面原型如图2所示。

通过插件做的接口模板页面，录入相关接口信息，其中：

请求方式支持：

OPTIONS：返回服务器针对特定资源所支持的HTTP请求方法。也可以利用向Web服务器发送'*'的请求来测试服务器的功能性。HEAD：向服务器索要与GET请求相一致的响应，只不过响应体将不会被返回。这一方法可以在不必传输整个响应内容的情况下，就可以获取包含在响应消息头中的元信息。

GET：向特定的资源发出请求。

POST：向指定资源提交数据进行处理请求(例如提交表单或者上传文件)。数据被包含在请求体中。POST请求可能会导致新的资源的创建和/或已有资源的修改。

PUT：向指定资源位置上传其最新内容。

DELETE：请求服务器删除Request-URI所标识的资源。

TRACE：回显服务器收到的请求，主要用于测试或诊断。

CONNECT：HTTP/1.1协议中预留给能够将连接改为管道方式的代理服务器。

请求数据类型返回数据类型：

ext/html：HTML格式

text/plain：纯文本格式

image/jpeg：jpg图片格式

application/json：JSON数据格式

application/x-www-form-urlencoded：form表单数据被编码为key/value格式发送到服务器(表单默认的提交数据格式)

multipart/form-data：在表单中进行文件上传时使用

状态：启用、停止、废弃

操作的添加、删除分别可以添加下一行，删除本行数据

生成文档：可以点击定义好接口数据模型，生成文件放在SpringBoot项目下的classpath中，所述classpath是SpringBoot资源文件的存放位置，以便存档和维护。

三：通过接口文件生成代码

下面将根据生成的接口文档选择相应文档进行接口代码生成。

1)定义选择接口文件的方法

通过插件action开发实现可以右键选择上面方法生成的接口文档，这块实现读取文件所在文件夹下文件列表进行可以多选操作，选择完成后，进行编译功能按钮，此时按钮携带选择的文件列表作为特定参数；

2)实现接口文件生成代码

通过注解处理器自定义一个编译期注解，该注解主要实现为，代码进行编译时，读取上面携带的特定参数，该参数为接口文档文件列表名，使用反射机制实现读取该接口文档列表参数进行遍历处理，同时开发控制层、业务层、PO层的代码模板，其中关键代码数据可由参数替换，这样遍历解析文件要素和请求返回参数后可套入代码模板，这样实现了以Java代码作为输入，生成文件(通常是.java文件)作为输出。

四：发布插件

自定义插件提交到Marketplace，注册Jetbrains账号，选择插件文件，选择License以及标签，点击Upload即可上传至Marketplace，系统审核后就能在Marketplace中搜索到插件下载使用了。

如图1所示，具体方法的流程包括：

使用IntelliJ IDEA下载接口文档插件；

IntelliJ IDEA内项目右键选择接口文档插件文档编辑；

插件页面内文档编辑；

编辑文档完成生成到项目静态资源目录；

IntelliJ IDEA内项目主启动类添加自定义读取文档生成代码的注解；

IntelliJ IDEA内项目右键选择接口文档插件文档生成代码，勾选需要生成代码的接口文件；

选择完成点击编译后生成代码文件。

有益效果：解决研发人员编写接口文档后再参照接口文档手动编写接口代码导致与接口文档不一致问题；

解决研发人员研发代码后再编写接口文档这种不规范情况，以及提供前端与外围关联系统时不及时问题。

以上的具体实施方式，对本发明的目的、技术方案和有益效果进行了进一步详细说明，所应理解的是，以上仅为本发明的具体实施方式而已，并不用于限定本发明的保护范围，凡在本发明的精神和原则之内，所做的任何修改、等同替换、改进等，均应包含在本发明的保护范围之内。