一种基于python与正则表达式的API文档自动生成方法及系统技术方案

本发明专利技术公开了一种基于python与正则表达式的API文档自动生成方法及系统，属于python正则表达式文本匹配技术领域，本发明专利技术要解决的技术问题为如何利用可匹配属性和不可匹配属性自动生成API文档，实现后端项目开发完成后编写大规模API文档省时省力，减少大量不必要的重复工作，采用的技术方案为：该方法是通过识别匹配概览文件中的可匹配属性值，填充API模块，自动生成API文档，文档中可匹配属性及值已自动生成，不可匹配属性自动生成值为空，值留待人工填充。该系统包括概览文件建立模块、API模板建立模块和识别匹配模块。

【技术实现步骤摘要】
一种基于python与正则表达式的API文档自动生成方法及系统
本专利技术涉及python正则表达式文本匹配
，具体地说是一种基于python与正则表达式的API文档自动生成方法及系统。
技术介绍
后端项目在开发完成后，需要为接口编写API文档说明，方便API调用者查阅。不同企业或个人有不同的文档编写方式，可以使用showdoc网站编写，也可以直接编写成markdown文件放置git远程仓库中。可是无论哪种方式，当项目API数量很多时，编写API文档都是件非常耗时耗力的问题。API文档存在一个共同特点：每条API都会存在API标题、APIURL、API描述、API请求方式、请求参数、响应参数、请求示例、响应示例等共同属性，只是属性值不同。这些共同属性中，API标题、APIURL、API描述、API请求方式都是可被正则表达式方便匹配的文本形式，称为可匹配属性；请求参数、响应参数属性一般情况下是表格的形式，示例等属性一般是json格式，这些属性内容复杂无规律，可匹配性不高，称为不可匹配属性。将可匹配属性值统一放置于概览文件中。故如何利用可匹配属性和不可匹配属性自动生成API文档，实现后端项目开发完成后编写大规模API文档省时省力，减少大量不必要的重复工作是目前现有技术中亟待解决的问题。专利号为CN107133079B的专利文献公开了一种基于问题报告的软件语义摘要自动生成方法，先构建开源软件信息数据库；然后获取项目托管社区中的问题报告数据和代码变更记录数据，并将之存储在数据库的问题报告数据表和代码变更记录数据表中；再使用正则表达式从代码变更记录中抽取其出现的问题报告id；然后对问题报告与软件代码进行位置匹配，最后进行语义提取与聚类，将生成的语义摘要存储在数据库的软件语义摘要数据表中。该技术方案通过软件的问题报告和代码变更记录为软件的代码文件或代码段自动标注语义信息，可提高开发人员复用软件的效率，但是未能解决后端项目开发完成后编写大规模API文档耗时耗力的问题。专利号为CN107193570A的专利文献公开了一种自动生成API文档的方法，包括：对原始后台代码执行附加apidoc注释的处理，得到附加apidoc注释的后台代码；对后台代码利用apidoc工具生成对应的API文档；当后台代码被修改时，相应的修改所述apidoc注释，得到最新版后台代码；将最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档。该技术方案能够以更加合理、更加及时的生成API文档的方法来消除因重复修改出现的遗漏生成最新版API文档的潜在隐患、提升后台与前端工程师之间的工作效率，但是未能解决后端项目开发完成后编写大规模API文档耗时耗力的问题。
技术实现思路
本专利技术的技术任务是提供一种基于python与正则表达式的API文档自动生成方法及系统，来解决如何利用可匹配属性和不可匹配属性自动生成API文档，实现后端项目开发完成后编写大规模API文档省时省力，减少大量不必要的重复工作的问题。本专利技术的技术任务是按以下方式实现的，一种基于python与正则表达式的API文档自动生成方法，该方法是通过识别匹配概览文件中的可匹配属性值，填充API模块，自动生成API文档，文档中可匹配属性及值已自动生成，不可匹配属性自动生成值为空，值留待人工填充；具体如下：S1、准备概览文件，写入可匹配属性值；S2、准备API模板，对应概览文件的可匹配属性值，在可匹配属性位置放置python占位符，留待填充；S3、通过识别匹配模块打开概览文件，读取并匹配一行数据，放置内存中；S4、识别匹配模块将内存中数据填充API模板，将该条API详情放入内存中；S5、判断API文档文件是否存在：①、若不存在，则新建；②、若存在，则将步骤S4内存中的填充好的API详情写入API文档中；S6、重复步骤S3到步骤S5的操作直到概览文件数据读取完成，即生成API文档。作为优选，所述步骤S6中生成API文档包括生成全部API文档和生成部分API文档。作为优选，所述概览文件为API文档的目录概览，概览文件中包含API中可匹配的属性值，起到目录索引的作用，方便API详情查阅。更优地，所述概览文件为markdown格式或文本形式，概览文件为markdown格式时能够被识别匹配模块匹配属性值，通过链接跳转的方式查阅API文档详细内容；markdown格式为文本形式时仅能够被识别匹配模块匹配属性值，无法起到链接跳转的作用。作为优选，所述API模板用于定义API的公共格式，使用python占位符放置于API可匹配的属性值位置，填充匹配数据；其中，API模板能够自由定义，提高了API文档格式的丰富性。作为优选，所述识别匹配模块由python语言编写，核心内容为正则表达式；识别匹配模块的工作过程具体如下：(1)、识别匹配模块打开准备好的概览文件；(2)、识别匹配模块读取并识别匹配每条API的属性值放入内存；(3)、将内存中的属性值填充API模板中对应的占位符，再将该条填充好的API模板写入API文档中，并判断API文档是否存在：①、若存在，则写入；②、若不存在，则新建；(4)、循环重复步骤(1)到步骤(3)，直到概览文件读取完成，即输出完整的API文档。更优地，所述生成部分API文档的具体步骤如下：(一)、将概览文件中所需部分的API属性值复制到系统剪切板；(二)、识别匹配模块读取剪贴板数据，与API模板合作识别匹配每条API的属性值放入内存；(三)、将内存中的属性值填充API模板中对应的占位符，再将该条填充好的API模板写入API文档中，并判断API文档是否存在：①、若存在，则写入；②、若不存在，则新建；(四)、循环重复步骤(一)到步骤(三)，直到概览文件读取完成，即输出生成部分API文档，即可该方式提供了API文档生成的多种需求。一种基于python与正则表达式的API文档自动生成系统，该系统包括，概览文件建立模块，用于建立API文档的目录概览文件，概览文件包含API中可匹配的属性值，起到目录索引的作用，方便API详情查阅；API模板建立模块，用于定义API的公共格式，使用python占位符放置于API可匹配属性值位置，填充匹配数据；识别匹配模块，用于识别概览文件并匹配属性值，再循环填充API模板生成API文档文件。作为优选，所述概览文件为markdown格式或文本形式，概览文件为markdown格式时能够被识别匹配模块匹配属性值，通过链接跳转的方式查阅API文档详细内容；markdown格式为文本形式时仅能够被识别匹配模块匹配属性值，无法起到链接跳转的作用。更优地，所述生成API文档文件包括生成全部API文档文件和生成部分API文档文件；所述生成全部API文档文件的工作过程具体如下：(1)、识别匹配模块本文档来自技高网...

【技术保护点】
1.一种基于python与正则表达式的API文档自动生成方法，其特征在于，该方法是通过识别匹配概览文件中的可匹配属性值，填充API模块，自动生成API文档，文档中可匹配属性及值已自动生成，不可匹配属性自动生成值为空，值留待人工填充；具体如下：/nS1、准备概览文件，写入可匹配属性值；/nS2、准备API模板，对应概览文件的可匹配属性值，在可匹配属性位置放置python占位符，留待填充；/nS3、通过识别匹配模块打开概览文件，读取并匹配一行数据，放置内存中；/nS4、识别匹配模块将内存中数据填充API模板，将该条API详情放入内存中；/nS5、判断API文档文件是否存在：/n①、若不存在，则新建；/n②、若存在，则将步骤S4内存中的填充好的API详情写入API文档中；/nS6、重复步骤S3到步骤S5的操作直到概览文件数据读取完成，即生成API文档。/n

【技术特征摘要】
1.一种基于python与正则表达式的API文档自动生成方法，其特征在于，该方法是通过识别匹配概览文件中的可匹配属性值，填充API模块，自动生成API文档，文档中可匹配属性及值已自动生成，不可匹配属性自动生成值为空，值留待人工填充；具体如下：
S1、准备概览文件，写入可匹配属性值；
S2、准备API模板，对应概览文件的可匹配属性值，在可匹配属性位置放置python占位符，留待填充；
S3、通过识别匹配模块打开概览文件，读取并匹配一行数据，放置内存中；
S4、识别匹配模块将内存中数据填充API模板，将该条API详情放入内存中；
S5、判断API文档文件是否存在：
①、若不存在，则新建；
②、若存在，则将步骤S4内存中的填充好的API详情写入API文档中；
S6、重复步骤S3到步骤S5的操作直到概览文件数据读取完成，即生成API文档。


2.根据权利要求1所述的基于python与正则表达式的API文档自动生成方法，其特征在于，所述步骤S6中生成API文档包括生成全部API文档和生成部分API文档。


3.根据权利要求1所述的基于python与正则表达式的API文档自动生成方法，其特征在于，所述概览文件为API文档的目录概览，概览文件中包含API中可匹配的属性值，起到目录索引的作用，方便API详情查阅。


4.根据权利要求1或2或3所述的基于python与正则表达式的API文档自动生成方法，其特征在于，所述概览文件为markdown格式或文本形式，概览文件为markdown格式时能够被识别匹配模块匹配属性值，通过链接跳转的方式查阅API文档详细内容；markdown格式为文本形式时仅能够被识别匹配模块匹配属性值，无法起到链接跳转的作用。


5.根据权利要求1所述的基于python与正则表达式的API文档自动生成方法，其特征在于，所述API模板用于定义API的公共格式，使用python占位符放置于API可匹配的属性值位置，填充匹配数据；其中，API模板能够自由定义，提高了API文档格式的丰富性。


6.根据权利要求1所述的基于python与正则表达式的API文档自动生成方法，其特征在于，所述识别匹配模块由python语言编写，核心内容为正则表达式；识别匹配模块的工作过程具体如下：
(1)、识别匹配模块打开准备好的概览文件；
(2)、识别匹配模块读取并识别匹配每条API的属性值放入内存；
(3)、将内存中的属性值填充API模板中对应的占位符，再将该条填充好的API模板写入API文档中，并判断API文档是否存在：
①、若存在，则写入；
②、若不存在，则新建；
(4)、循环重复步骤(1)到步骤(3)，直到概览文件读取完成，即输出完整的API文档。


7.根据权利要求2所述的基于pyth...

【专利技术属性】
技术研发人员：姜昱鹏，徐士强，宋亚萍，
申请(专利权)人：山东汇贸电子口岸有限公司，
类型：发明
国别省市：山东;37