CN113672204A - 一种接口文档生成方法、***、电子设备及存储介质 - Google Patents

Abstract

本发明提出一种接口文档生成方法、***、电子设备及存储介质，其方法技术方案包括开发环境配置步骤，在一Java集成开发环境中配置EasyYapi插件；规范框架配置步骤，在所述Java集成开发环境中的一Java项目中，添加一Swagger规范框架依赖，并将所述EasyYapi插件和所述Swagger规范框架依赖进行整合；接口文档生成步骤，通过所述EasyYapi插件上传接口信息并在Yapi上生成接口文档。本申请解决了现有前后端接口协调方法准确性、实时性和详细性较差的问题。

Description

一种接口文档生成方法、***、电子设备及存储介质

技术领域

本发明属于接口技术领域，尤其涉及一种接口文档生成方法、***、电子设备及存储介质。

背景技术

随着互联网的高速发展，前端页面的展示、交互体验越来越灵活、炫丽，响应体验也要求越来越高，后端服务的高并发、高可用、高性能、高扩展等特性的要求也愈加严格，从而导致前后端研发各自专注于自己擅长的领域深耕细作，前后端分离已成为互联网项目开发的业界标准使用方式。

前后端分离的优势是一套api可被多个客户端复用，分工和协作被细化，大大提高了编码效率。然而与此同时带来了另一个问题：双方之间关注甚少，在没有任何api(Application Programming Interface，即应用程序编程接口)约定规范情况下各自为政，导致在产品项目开发过程中，前后端的api联调对接工作量占比在30％-50％左右，甚至会更高。如何提高前后端api联调对接工作效率成为整个产品项目研发的关键。

为了解决上述问题，基于api文档的开发前后端协作方式应运而生，后端编写和维护接口文档，在api变化时更新接口文档；后端根据接口文档进行接口开发；前端根据接口文档进行开发+Mock(数据模拟)平台；开发完成后联调和提交测试。通过接口文档，开发时，前后端工程师有一个统一的文件进行沟通交流开发；维护时，可以方便后期人员查看和维护。

但在现有技术中，传统的接口文档产出，基本上是由后端进行手工编写。在编写文档过程中，由于人为的粗心大意，造成接口文档某个字段，或者某个接口名写错，这些错误就会影响后续的联调操作。在项目开发过程中，当后端人员提供了一份接口文档，并且与前端人员联调也通过了，但是由于需求变更，导致后端接口发生了变化，而后端人员有可能懒，又没有实时的去更新接口文档，那么前端人员就无法根据最新的接口文档进行修改，从而无法有效的完成整个项目的需求变更。在进行接口文档编写时，基本上都会有一个标准，包括接口名、方法类型、入参、入参类型，返回值，返回值的各种情况说明等等。一般公司都会通过接口文档规范来强制大家按照要求编写，但是理想很美好，现实很残酷。随着时间推移，项目迭代次数过多，或者项目周期赶等等因素，大家很难能够完全按照规范来编写接口文档。由于接口文档的不够规范，描述不够详细，对于接口文档的需求方会造成困扰。

发明内容

本申请实施例提供了一种接口文档生成方法、***、电子设备及存储介质，以至少解决现有前后端接口协调方法准确性、实时性和详细性较差的问题。

第一方面，本申请实施例提供了一种接口文档生成方法，包括：开发环境配置步骤，在一Java集成开发环境中配置EasyYapi插件；规范框架配置步骤，在所述Java集成开发环境中的一Java项目中，添加一Swagger规范框架依赖，并将所述EasyYapi插件和所述Swagger规范框架依赖进行整合；接口文档生成步骤，通过所述EasyYapi插件上传接口信息并在Yapi上生成接口文档。

优选的，所述规范框架配置步骤进一步包括：在所述Java项目中，通过pom文件引入Swagger依赖，并在项目程序启动入口Application上添加@EnableOpenApi注解，进一步在所述接口信息添加Swagger配置以添加所述Swagger规范框架依赖。

优选的，所述规范框架配置步骤进一步包括：所述Swagger配置包括注解@Api和@ApiOperation，其中，所述注解@Api用于接口大类，所述注解@ApiOperation用于具体接口。

优选的，所述接口文档生成步骤进一步包括：若所述接口信息发生变更，则重复执行所述接口文档生成步骤对所述Yapi上的所述接口文档进行更新。

第二方面，本申请实施例提供了一种接口文档生成***，适用于上述一种接口文档生成方法，包括：开发环境配置模块，在一Java集成开发环境中配置EasyYapi插件；规范框架配置模块，在所述Java集成开发环境中的一Java项目中，添加一Swagger规范框架依赖，并将所述EasyYapi插件和所述Swagger规范框架依赖进行整合；接口文档生成模块，通过所述EasyYapi插件上传接口信息并在Yapi上生成接口文档。

在其中一些实施例中，所述规范框架配置模块进一步包括：在所述Java项目中，通过pom文件引入Swagger依赖，并在项目程序启动入口Application上添加@EnableOpenApi注解，进一步在所述接口信息添加Swagger配置以添加所述Swagger规范框架依赖。

在其中一些实施例中，所述规范框架配置模块进一步包括：所述Swagger配置包括注解@Api和@ApiOperation，其中，所述注解@Api用于接口大类，所述注解@ApiOperation用于具体接口。

在其中一些实施例中，所述接口文档生成模块进一步包括：若所述接口信息发生变更，则重复执行所述接口文档生成模块对所述Yapi上的所述接口文档进行更新。

第三方面，本申请实施例提供了一种电子设备，包括存储器、处理器以及存储在所述存储器上并可在所述处理器上运行的计算机程序，所述处理器执行所述计算机程序时实现如上述第一方面所述的一种接口文档生成方法。

第四方面，本申请实施例提供了一种计算机可读存储介质，其上存储有计算机程序，该程序被处理器执行时实现如上述第一方面所述的一种接口文档生成方法。

本申请可应用于数据能力技术领域。相比于相关技术，本申请实施例提供的一种接口文档生成方法，从实际产品项目开发问题出发，为了解决产品项目开发中碰到的api文档与实际代码不一致、根据需求变更不及时、描述不够规范详细等问题，基于javaSpringBoot项目，通过Swagger规范框架和EasyYapi插件，将代码自动部署到Yapi接口管理平台上，实现了一种准确，高效的产品项目api文档的自动生成方法。相对于其他的api文档生成方法，有如下优点：

1.当api发生改变时，修改灵活；

2.后端代码修改，前端能够通过自动生成的api文档实时感知到变动；

3.产品项目代码与api文档时刻保持一致。

附图说明

此处所说明的附图用来提供对本申请的进一步理解，构成本申请的一部分，本申请的示意性实施例及其说明用于解释本申请，并不构成对本申请的不当限定。在附图中：

图1为本发明的接口文档生成方法流程图；

图2为本发明的接口文档生成***的框架图；

图3为本发明的电子设备的框架图；

以上图中：

1、开发环境配置模块；2、规范框架配置模块；3、接口文档生成模块；60、总线；61、处理器；62、存储器；63、通信接口。

具体实施方式

为了使本申请的目的、技术方案及优点更加清楚明白，以下结合附图及实施例，对本申请进行描述和说明。应当理解，此处所描述的具体实施例仅仅用以解释本申请，并不用于限定本申请。基于本申请提供的实施例，本领域普通技术人员在没有作出创造性劳动的前提下所获得的所有其他实施例，都属于本申请保护的范围。

显而易见地，下面描述中的附图仅仅是本申请的一些示例或实施例，对于本领域的普通技术人员而言，在不付出创造性劳动的前提下，还可以根据这些附图将本申请应用于其他类似情景。此外，还可以理解的是，虽然这种开发过程中所作出的努力可能是复杂并且冗长的，然而对于与本申请公开的内容相关的本领域的普通技术人员而言，在本申请揭露的技术内容的基础上进行的一些设计，制造或者生产等变更只是常规的技术手段，不应当理解为本申请公开的内容不充分。

在本申请中提及“实施例”意味着，结合实施例描述的特定特征、结构或特性可以包含在本申请的至少一个实施例中。在说明书中的各个位置出现该短语并不一定均是指相同的实施例，也不是与其它实施例互斥的独立的或备选的实施例。本领域普通技术人员显式地和隐式地理解的是，本申请所描述的实施例在不冲突的情况下，可以与其它实施例相结合。

除非另作定义，本申请所涉及的技术术语或者科学术语应当为本申请所属技术领域内具有一般技能的人士所理解的通常意义。本申请所涉及的“一”、“一个”、“一种”、“该”等类似词语并不表示数量限制，可表示单数或复数。本申请所涉及的术语“包括”、“包含”、“具有”以及它们任何变形，意图在于覆盖不排他的包含；例如包含了一系列步骤或模块(单元)的过程、方法、***、产品或设备没有限定于已列出的步骤或单元，而是可以还包括没有列出的步骤或单元，或可以还包括对于这些过程、方法、产品或设备固有的其它步骤或单元。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful(Representational State Transfer，一种网络应用程序的设计风格和开发方式)风格的Web服务。同时，Swagger遵循了OpenAPI规范，OpenAPI是Linux基金会的一个项目，试图通过定义一种用来描述api格式或api定义的语言，来规范RESTful服务开发过程。

通过这套规范，只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

YApi是高效、易用、功能强大的api管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护API，YApi还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

本发明基于Swagger规范框架+EasyYapi插件+Yapi接口管理平台实现整个方法流程。

以下，结合附图详细介绍本发明的实施例：

图1为本发明的接口文档生成方法流程图，请参见图1，本发明接口文档生成方法包括如下步骤：

S1：在一Java集成开发环境中配置EasyYapi插件。

在具体实施中，本申请实施例使用Java集成开发环境IDEA，并在IDEA中安装EasyYapi插件。

S2：在所述Java集成开发环境中的一Java项目中，添加一Swagger规范框架依赖，并将所述EasyYapi插件和所述Swagger规范框架依赖进行整合。

可选的，在所述Java项目中，通过pom文件引入Swagger依赖，并在项目程序启动入口Application上添加@EnableOpenApi注解，进一步在所述接口信息添加Swagger配置以添加所述Swagger规范框架依赖。

可选的，所述规范框架配置步骤进一步包括：所述Swagger配置包括注解@Api和@ApiOperation，其中，所述注解@Api用于接口大类，所述注解@ApiOperation用于具体接口。

在具体实施中，在Java项目添加Swagger规范框架支持，首先通过pom文件引入Swagger依赖，并在项目启动入口Application上添加@EnableOpenApi注解，使项目启用Swagger规范框架，可选的，在项目中配置Swagger前端显示所需的标题、文档描述、版本等信息，最后，api接口添加Swagger相关配置，相关配置包括主要注解@Api和@ApiOperation。其中，注解@Api用于一个api接口大类上，参数tags用于说明该系列api接口的作用；注解@ApiOperation用于该系列下具体api接口上，参数value用于说明该api的具体作用。

S3：通过所述EasyYapi插件上传接口信息并在Yapi上生成接口文档。可选的，若所述接口信息发生变更，则重复执行所述接口文档生成步骤对所述Yapi上的所述接口文档进行更新。

在具体实施中，使用EasyYapi插件自动生成api文档到Yapi接口管理平台，选择并上传想要上传的api接口，输入导入Yapi接口管理平台对应项目的token，成功后可在Yapi接口管理平台上查看对应的接口。在具体实施中，如果api接口发生的变更，如修改、新增、删除等，可重复执行，再次上传到Yapi接口管理平台，Yapi上对应的文档会被更新。

需要说明的是，在上述流程中或者附图的流程图中示出的步骤可以在诸如一组计算机可执行指令的计算机***中执行，并且，虽然在流程图中示出了逻辑顺序，但是在某些情况下，可以以不同于此处的顺序执行所示出或描述的步骤。

本申请实施例提供了一种接口文档生成***，适用于上述的一种接口文档生成方法。如以下所使用的，术语“单元”、“模块”等可以实现预定功能的软件和/或硬件的组合。尽管以下实施例所描述的装置较佳地以软件来实现，但是硬件、或者软件和硬件的组合的实现也是可能并被构想的。

图2为根据本发明的接口文档生成***的框架图，请参见图2，包括：

开发环境配置模块1：在一Java集成开发环境中配置EasyYapi插件。

在具体实施中，本申请实施例使用Java集成开发环境IDEA，并在IDEA中安装EasyYapi插件。

规范框架配置模块2：在所述Java集成开发环境中的一Java项目中，添加一Swagger规范框架依赖，并将所述EasyYapi插件和所述Swagger规范框架依赖进行整合。

可选的，在所述Java项目中，通过pom文件引入Swagger依赖，并在项目程序启动入口Application上添加@EnableOpenApi注解，进一步在所述接口信息添加Swagger配置以添加所述Swagger规范框架依赖。

可选的，所述规范框架配置步骤进一步包括：所述Swagger配置包括注解@Api和@ApiOperation，其中，所述注解@Api用于接口大类，所述注解@ApiOperation用于具体接口。

在具体实施中，在Java项目添加Swagger规范框架支持，首先通过pom文件引入Swagger依赖，并在项目启动入口Application上添加@EnableOpenApi注解，使项目启用Swagger规范框架，可选的，在项目中配置Swagger前端显示所需的标题、文档描述、版本等信息，最后，api接口添加Swagger相关配置，相关配置包括主要注解@Api和@ApiOperation。其中，注解@Api用于一个api接口大类上，参数tags用于说明该系列api接口的作用；注解@ApiOperation用于该系列下具体api接口上，参数value用于说明该api的具体作用。

接口文档生成模块3：通过所述EasyYapi插件上传接口信息并在Yapi上生成接口文档。可选的，若所述接口信息发生变更，则重复执行所述接口文档生成模块3对所述Yapi上的所述接口文档进行更新。

在具体实施中，使用EasyYapi插件自动生成api文档到Yapi接口管理平台，选择并上传想要上传的api接口，输入导入Yapi接口管理平台对应项目的token，成功后可在Yapi接口管理平台上查看对应的接口。在具体实施中，如果api接口发生的变更，如修改、新增、删除等，可重复执行，再次上传到Yapi接口管理平台，Yapi上对应的文档会被更新。

另外，结合图1描述的一种接口文档生成方法可以由电子设备来实现。图3为本发明的电子设备的框架图。

电子设备可以包括处理器61以及存储有计算机程序指令的存储器62。

具体地，上述处理器61可以包括中央处理器(CPU)，或者特定集成电路(Application Specific Integrated Circuit，简称为ASIC)，或者可以被配置成实施本申请实施例的一个或多个集成电路。

其中，存储器62可以包括用于数据或指令的大容量存储器。举例来说而非限制，存储器62可包括硬盘驱动器(Hard Disk Drive，简称为HDD)、软盘驱动器、固态驱动器(SolidState Drive，简称为SSD)、闪存、光盘、磁光盘、磁带或通用串行总线(Universal SerialBus，简称为USB)驱动器或者两个或更多个以上这些的组合。在合适的情况下，存储器62可包括可移除或不可移除(或固定)的介质。在合适的情况下，存储器62可在数据处理装置的内部或外部。在特定实施例中，存储器62是非易失性(Non-Volatile)存储器。在特定实施例中，存储器62包括只读存储器(Read-Only Memory，简称为ROM)和随机存取存储器(RandomAccess Memory，简称为RAM)。在合适的情况下，该ROM可以是掩模编程的ROM、可编程ROM(Programmable Read-Only Memory，简称为PROM)、可擦除PROM(Erasable ProgrammableRead-Only Memory，简称为EPROM)、电可擦除PROM(Electrically Erasable ProgrammableRead-OnlyMemory，简称为EEPROM)、电可改写ROM(Electrically Alterable Read-OnlyMemory，简称为EAROM)或闪存(FLASH)或者两个或更多个以上这些的组合。在合适的情况下，该RAM可以是静态随机存取存储器(Static Random-AccessMemory，简称为SRAM)或动态随机存取存储器(Dynamic Random Access Memory，简称为DRAM)，其中，DRAM可以是快速页模式动态随机存取存储器(Fast Page Mode Dynamic Random Access Memory，简称为FPMDRAM)、扩展数据输出动态随机存取存储器(Extended Date Out Dynamic RandomAccess Memory，简称为EDODRAM)、同步动态随机存取内存(Synchronous Dynamic Random-Access Memory，简称SDRAM)等。

存储器62可以用来存储或者缓存需要处理和/或通信使用的各种数据文件，以及处理器61所执行的可能的计算机程序指令。

处理器61通过读取并执行存储器62中存储的计算机程序指令，以实现上述实施例中的任意一种接口文档生成方法。

在其中一些实施例中，电子设备还可包括通信接口63和总线60。其中，如图3所示，处理器61、存储器62、通信接口63通过总线60连接并完成相互间的通信。

通信端口63可以实现与其他部件例如：外接设备、图像/数据采集设备、数据库、外部存储以及图像/数据处理工作站等之间进行数据通信。

总线60包括硬件、软件或两者，将电子设备的部件彼此耦接在一起。总线60包括但不限于以下至少之一：数据总线(Data Bus)、地址总线(Address Bus)、控制总线(ControlBus)、扩展总线(Expansion Bus)、局部总线(Local Bus)。举例来说而非限制，总线60可包括图形加速接口(Accelerated Graphics Port，简称为AGP)或其他图形总线、增强工业标准架构(Extended Industry Standard Architecture，简称为EISA)总线、前端总线(FrontSide Bus，简称为FSB)、超传输(Hyper Transport，简称为HT)互连、工业标准架构(Industry Standard Architecture，简称为ISA)总线、无线带宽(InfiniBand)互连、低引脚数(Low Pin Count，简称为LPC)总线、存储器总线、微信道架构(Micro ChannelArchitecture，简称为MCA)总线、***组件互连(Peripheral Component Interconnect，简称为PCI)总线、PCI-Express(PCI-X)总线、串行高级技术附件(Serial AdvancedTechnology Attachment，简称为SATA)总线、视频电子标准协会局部(Video ElectronicsStandards Association Local Bus，简称为VLB)总线或其他合适的总线或者两个或更多个以上这些的组合。在合适的情况下，总线60可包括一个或多个总线。尽管本申请实施例描述和示出了特定的总线，但本申请考虑任何合适的总线或互连。

该电子设备可以执行本申请实施例中的一种接口文档生成方法。

另外，结合上述实施例中的一种接口文档生成方法，本申请实施例可提供一种计算机可读存储介质来实现。该计算机可读存储介质上存储有计算机程序指令；该计算机程序指令被处理器执行时实现上述实施例中的任意一种接口文档生成方法。

而前述的存储介质包括：U盘、移动硬盘、只读存储器(ReadOnly Memory，简称为ROM)、随机存取存储器(Random Access Memory，简称为RAM)、磁碟或者光盘等各种可以存储程序代码的介质。

以上所述实施例的各技术特征可以进行任意的组合，为使描述简洁，未对上述实施例中的各个技术特征所有可能的组合都进行描述，然而，只要这些技术特征的组合不存在矛盾，都应当认为是本说明书记载的范围。

以上所述实施例仅表达了本申请的几种实施方式，其描述较为具体和详细，但并不能因此而理解为对发明专利范围的限制。应当指出的是，对于本领域的普通技术人员来说，在不脱离本申请构思的前提下，还可以做出若干变形和改进，这些都属于本申请的保护范围。因此，本申请专利的保护范围应以所附权利要求为准。

Claims (10)

1.一种接口文档生成方法，其特征在于，包括：

开发环境配置步骤，在一Java集成开发环境中配置EasyYapi插件；

规范框架配置步骤，在所述Java集成开发环境中的一Java项目中，添加一Swagger规范框架依赖，并将所述EasyYapi插件和所述Swagger规范框架依赖进行整合；

接口文档生成步骤，通过所述EasyYapi插件上传接口信息并在Yapi上生成接口文档。

2.根据权利要求1所述的接口文档生成方法，其特征在于，所述规范框架配置步骤进一步包括：在所述Java项目中，通过pom文件引入Swagger依赖，并在项目程序启动入口Application上添加@EnableOpenApi注解，进一步在所述接口信息添加Swagger配置以添加所述Swagger规范框架依赖。

3.根据权利要求2所述的接口文档生成方法，其特征在于，所述规范框架配置步骤进一步包括：所述Swagger配置包括注解@Api和@ApiOperation，其中，所述注解@Api用于接口大类，所述注解@ApiOperation用于具体接口。

4.根据权利要求1所述的接口文档生成方法，其特征在于，所述接口文档生成步骤进一步包括：若所述接口信息发生变更，则重复执行所述接口文档生成步骤对所述Yapi上的所述接口文档进行更新。

5.一种接口文档生成***，其特征在于，包括：

开发环境配置模块，在一Java集成开发环境中配置EasyYapi插件；

规范框架配置模块，在所述Java集成开发环境中的一Java项目中，添加一Swagger规范框架依赖，并将所述EasyYapi插件和所述Swagger规范框架依赖进行整合；

接口文档生成模块，通过所述EasyYapi插件上传接口信息并在Yapi上生成接口文档。

6.根据权利要求5所述的接口文档生成***，其特征在于，所述规范框架配置模块进一步包括：在所述Java项目中，通过pom文件引入Swagger依赖，并在项目程序启动入口Application上添加@EnableOpenApi注解，进一步在所述接口信息添加Swagger配置以添加所述Swagger规范框架依赖。

7.根据权利要求6所述的接口文档生成***，其特征在于，所述规范框架配置模块进一步包括：所述Swagger配置包括注解@Api和@ApiOperation，其中，所述注解@Api用于接口大类，所述注解@ApiOperation用于具体接口。

8.根据权利要求5所述的接口文档生成***，其特征在于，所述接口文档生成模块进一步包括：若所述接口信息发生变更，则重复执行所述接口文档生成模块对所述Yapi上的所述接口文档进行更新。

9.一种电子设备，包括存储器、处理器以及存储在所述存储器上并可在所述处理器上运行的计算机程序，其特征在于，所述处理器执行所述计算机程序时实现如权利要求1至4中任一项所述的接口文档生成方法。

10.一种计算机可读存储介质，其上存储有计算机程序，其特征在于，该程序被处理器执行时实现如权利要求1至4中任一项所述的接口文档生成方法。

Images