CN113296752A - 生成api文档的方法、系统、设备及存储介质 - Google Patents

生成api文档的方法、系统、设备及存储介质 Download PDF

Info

Publication number
CN113296752A
CN113296752A CN202110568595.0A CN202110568595A CN113296752A CN 113296752 A CN113296752 A CN 113296752A CN 202110568595 A CN202110568595 A CN 202110568595A CN 113296752 A CN113296752 A CN 113296752A
Authority
CN
China
Prior art keywords
java
api
information
request
java object
Prior art date
Legal status (The legal status is an assumption and is not a legal conclusion. Google has not performed a legal analysis and makes no representation as to the accuracy of the status listed.)
Pending
Application number
CN202110568595.0A
Other languages
English (en)
Inventor
卢俊杰
Current Assignee (The listed assignees may be inaccurate. Google has not performed a legal analysis and makes no representation or warranty as to the accuracy of the list.)
Ping An Pension Insurance Corp
Original Assignee
Ping An Pension Insurance Corp
Priority date (The priority date is an assumption and is not a legal conclusion. Google has not performed a legal analysis and makes no representation as to the accuracy of the date listed.)
Filing date
Publication date
Application filed by Ping An Pension Insurance Corp filed Critical Ping An Pension Insurance Corp
Priority to CN202110568595.0A priority Critical patent/CN113296752A/zh
Publication of CN113296752A publication Critical patent/CN113296752A/zh
Pending legal-status Critical Current

Links

Images

Classifications

    • GPHYSICS
    • G06COMPUTING; CALCULATING OR COUNTING
    • G06FELECTRIC DIGITAL DATA PROCESSING
    • G06F8/00Arrangements for software engineering
    • G06F8/30Creation or generation of source code
    • G06F8/31Programming languages or programming paradigms
    • GPHYSICS
    • G06COMPUTING; CALCULATING OR COUNTING
    • G06FELECTRIC DIGITAL DATA PROCESSING
    • G06F8/00Arrangements for software engineering
    • G06F8/40Transformation of program code
    • G06F8/41Compilation
    • G06F8/42Syntactic analysis
    • G06F8/427Parsing
    • GPHYSICS
    • G06COMPUTING; CALCULATING OR COUNTING
    • G06FELECTRIC DIGITAL DATA PROCESSING
    • G06F8/00Arrangements for software engineering
    • G06F8/70Software maintenance or management
    • G06F8/73Program documentation
    • GPHYSICS
    • G06COMPUTING; CALCULATING OR COUNTING
    • G06FELECTRIC DIGITAL DATA PROCESSING
    • G06F9/00Arrangements for program control, e.g. control units
    • G06F9/06Arrangements for program control, e.g. control units using stored programs, i.e. using an internal store of processing equipment to receive or retain programs
    • G06F9/44Arrangements for executing specific programs
    • G06F9/455Emulation; Interpretation; Software simulation, e.g. virtualisation or emulation of application or operating system execution engines
    • G06F9/45504Abstract machines for programme code execution, e.g. Java virtual machine [JVM], interpreters, emulators
    • G06F9/45508Runtime interpretation or emulation, e g. emulator loops, bytecode interpretation

Landscapes

  • Engineering & Computer Science (AREA)
  • Software Systems (AREA)
  • Theoretical Computer Science (AREA)
  • General Engineering & Computer Science (AREA)
  • Physics & Mathematics (AREA)
  • General Physics & Mathematics (AREA)
  • Library & Information Science (AREA)
  • Computing Systems (AREA)
  • Devices For Executing Special Programs (AREA)

Abstract

一种生成API文档的方法、系统、设备及存储介质,其中生成API文档的方法包括以下步骤:通过在Java虚拟机中加载预设的代理程序从所述Java虚拟机中运行的Java字节码中获取所有的Java类;从获取的所述Java类中,过滤出暴露目标API的类,所述目标API至少存在一个;从所述暴露目标API的类中过滤出所述暴露目标API的方法;从所述暴露目标API的方法中提取出参数信息以及注解信息;将每一个目标API的注解信息与参数信息进行合并,生成所述每一个目标API对应的第一Java对象,并将所述第一Java对象存储至内存中;将所述第一Java对象转化成第一Json报文;将所述第一Json报文导入Swagger框架以通过所述Swagger框架将所述第一Json报文转化成API文档。

Description

生成API文档的方法、系统、设备及存储介质
技术领域
本发明涉及于软件开发技术领域,尤其一种生成API文档的方法、系统、设备及存储介质。
背景技术
Java是现有的具有可移植性的用于编写程序的高级编程语言,其中系统和应用程序通过应用程序接口(API,Application Programming Interface)进行通信。其中API(Application Programming Interface,应用程序编程接口)是一些预先定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码,或理解内部工作机制的细节;而API文档是一个关于API的技术内容交付文件,包含如何有效地使用和集成API的说明。它是一个简明的参考手册,包含了使用API所需的所有信息,详细介绍了函数、类、返回类型、参数等。
然而在使用Java进行研发过程中,跨平台或跨系统的API调用需要通过使用API文档中关于API的调用及其涉及到的参数的解释说明来进行通信交互规范。一般来说,API文档通过人工撰写的方式或者自动化生成的方式来形成的。
对于API文档自动生成的方式来说,现业内在开发过程中,API文档会通过使用Swagger这个框架来生成,但是通过Swagger框架进行API的文档生成存在着以下问题。
问题一、在Swagger框架下需要研发人员在编写业务代码的同时在代码中加入大量的关于Swagger框架的Swagger注解用来生成相关的API文档,而Swagger注解随着业务代码在编译阶段带入Java字节码中,在业务代码实际运行的时候Swagger框架的功能会一直占用业务代码的Java虚拟机(JVM)的内存。
问题二、在项目后期将Swagger注解剥离出来十分困难。
问题三、开发人员修改了API之后需要不断维护侵入式地跟进业务代码的Swagger注解以维护API文档和代码的一致性,消耗了开发人员的时间和精力的同时还增加了项目推进的时间。
综上所述,由于通过Swagger生成API文档的过程中,至少存在上述3个问题,导致使用Swagger注解来生成API文档时具有许多不便和负担。
发明内容
本发明的一个目的在于提供一种生成API文档的方法、系统、设备及存储介质,其中所述生成API文档的方法根据API的Java字节码并通过Swagger框架生成API文档,以减少代码注解对开发人员和计算机产生负担。
为了实现上述目的,本发明提供一种生成API文档的方法,包括以下步骤:
通过在Java虚拟机中加载预设的代理程序从所述Java虚拟机中运行的Java字节码中获取所有的Java类;
从获取的所述Java类中,过滤出暴露目标API的类,所述目标API至少存在一个;
从所述暴露目标API的类中过滤出所述暴露目标API的方法;
从所述暴露目标API的方法中提取出参数信息以及注解信息;
将每一个目标API的注解信息与参数信息进行合并,生成所述每一个目标API对应的第一Java对象,并将所述第一Java对象存储至内存中;
将所述第一Java对象转化成第一Json报文;
将所述第一Json报文导入Swagger框架以通过所述Swagger框架将所述第一Json报文转化成API文档。
可选的,所述生成API文档的方法还包括:
在所述Java虚拟机中拦截接收到的服务请求;
对所述服务请求进行解析,得到所述服务请求中包含的统一资源定位器信息、请求方法信息及请求头信息;
从所述内存中找到与所述统一资源定位器信息、所述请求方法信息及所述请求头信息相对应的第二Java对象;
根据所述请求头信息从所述服务请求中获取请求参数;
根据所述请求参数与所述第二Java对象中的参数进行比较的比较结果,调整所述第二Java对象中的参数;
将调整后的第二Java对象转化为新的Json报文。
可选的,所述生成API文档的方法还包括:
获取用户预先设置的过滤条件,所述过滤条件包括所述预设数值对应的字段,与非预设数值对应的字段;
可选的,所述将调整后的第二Java对象转化为新的Json报文包括:
将调整后的第二Java对象中满足所述过滤条件的字段过滤掉,得到过滤后的第二Java对象;
将过滤后的第二Java对象转化为新的Json报文。
可选的,所述根据所述请求头信息从所述服务请求中获取请求参数包括:
根据所述请求头信息中的内容类型信息,从所述服务请求中获取请所述求参数信息。
可选的,所述根据所述请求参数与所述第二Java对象中的参数进行比较的比较结果,调整所述第二Java对象中的参数,包括:
若所述比较结果为所述请求参数和所述第二Java对象的中的参数名相同,则将所述参数名对应的字段标记为预设数值,以在生成新的Json报文时保留所述字段。
可选的,所述通过在Java虚拟机中加载预设的代理程序从所述Java虚拟机中运行的Java字节码中获取所有的Java类包括:
通过所述代理程序调用预设的类加载器,从所述Java虚拟机中运行的Java字节码中获取所有的Java类。
可选的,所述从获取的所述Java类中,过滤出暴露API的类包括:
通过调用所述Java中的方法,过滤出存在控制器类注解的Java类。
为了实现上述目的,本发明还一种生成API文档的系统,包括:
获取模块,用于通过在Java虚拟机中加载预设的代理程序从所述Java虚拟机中运行的Java字节码中获取所有的Java类;
第一过滤模块,用于从获取的所述Java类中,过滤出暴露目标API的类,所述目标API至少存在一个;
第二过滤模块,用于从所述暴露目标API的类中过滤出所述暴露目标API的方法;
抽取模块,用于从所述暴露目标API的方法中提取出参数信息以及注解信息;
生成模块,用于将每一个目标API的注解信息与参数信息进行合并,生成所述每一个目标API对应的第一Java对象,并将所述第一Java对象存储至内存中;
转化模块,用于将所述第一Java对象转化成第一Json报文;
导入模块,用于将所述第一Json报文导入Swagger框架以通过所述Swagger框架将所述第一Json报文转化成API文档。
拦截模块,在所述Java虚拟机中拦截接收到的服务请求;
解析模块,对所述服务请求进行解析,得到所述服务请求中包含的统一资源定位器信息、请求方法信息及请求头信息;
寻找模块,从所述内存中找到与所述统一资源定位器信息、所述请求方法信息及所述请求头信息相对应的第二Java对象;
获参模块,根据所述请求头信息从所述服务请求中获取请求参数;
调整模块,根据所述请求参数与所述第二Java对象中的参数进行比较的比较结果,调整所述第二Java对象中的参数;
筛选模块,将调整后的第二Java对象转化为新的Json报文。
为实现上述目的,本发明还提供一种计算机设备,包括存储器以及处理器,所述存储器中存储有可在所述处理器上运行的计算机程序,所述处理器执行所述计算机程序时,实现上述生成API文档方法的步骤。
为实现上述目的,本发明还提供一种生成API文档的可读存储介质,其中所述可读存储介质用于存储所所述生成API文档的系统,以被处理器执行时实现上述生成API文档的方法。
本实施例中的生成API文档的方法相对于现有技术而言,不需要对于业务代码而言进行侵入式编写所述Swagger框架的注解来利用Swagger框架生成可视化的API文档,其中利用所述Swagger框架,只需要按照所述Swagger框架的规范去定义接口及接口相关的信息,再通过Swagger框架衍生出来的一系列项目和工具,就可以做到生成各种格式的API文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。
附图说明
图1是根据本发明实施例的生成API文档的方法流程示意图;
图2是根据本发明另一实施例的生成API文档的方法流程示意图;
图3是根据本发明实施例的生成API文档的系统的模块示意图;
图4是根据本发明实施例的一种可选的硬件架构示意图。
本发明目的的实现、功能特点及优点将结合实施例,参照附图做进一步说明。
具体实施方式
这里将详细地对示例性发明实施例进行说明,其示例表示在附图中。下面的描述涉及附图时,除非另有表示,不同附图中的相同数字表示相同或相似的要素。以下示例性发明实施例中所描述的实施方式并不代表与本发明相一致的所有实施方式。相反,它们仅是与如所附权利要求书中所详述的、本发明的一些方面相一致的系统和方法的例子。
在本发明使用的术语是仅仅出于描述特定发明实施例的目的,而非旨在限制本发明。在本发明和所附权利要求书中所使用的单数形式的“一种”、“所述”和“该”也旨在包括多数形式,除非上下文清楚地表示其他含义。还应当理解,本文中使用的术语“和/或”是指并包含一个或多个相关联的列出项目的任何或所有可能组合。
应当理解,尽管在本发明可能采用术语第一、第二、第三等来描述各种信息,但这些信息不应限于这些术语。这些术语仅用来将同一类型的信息彼此区分开。例如,在不脱离本发明范围的情况下,第一信息也可以被称为第二信息,类似地,第二信息也可以被称为第一信息。取决于语境,如在此所使用的词语“如果”可以被解释成为“在……时”或“当……时”或“响应于确定”。
在本发明的描述中,需要理解的是,步骤前的数字标号并不标识执行步骤的前后顺序,仅用于方便描述本发明及区别每一步骤,因此不能理解为对本发明的限制。基于本发明中的发明实施例,本领域普通技术人员在没有做出创造性劳动前提下所获得的所有其他发明实施例,都属于本发明保护的范围。
下面结合附图对本发明实施例进行说明。
参阅图1,示出了本发明一实施例之生成API文档的方法的流程图。可以理解,本方法实施例中的流程图不对执行步骤的顺序进行限定。下面以客户标签的生成装置(下文以“生成装置”简称)为执行主体进行示例性描述,所述生成装置可以应用于计算机设备中,所述计算机设备可以是移动电话、平板个人计算机(tablet personal computer)、膝上型计算机(laptop computer)、服务器等具有数据传输功能的设备。所述方法包括以下步骤:
S101.通过在Java虚拟机中加载预设的代理程序从Java虚拟机中运行的Java字节码中获取所有的Java类;
具体地,基于JVMTI机制,所述代理程序通过利用Instrumentation中的类加载器,也就是通过调用inst.getAllLoadedClasses()方法,从运行中的Java字节码中获取所有被加载到Java虚拟机运行的Java类。
其中所述JVMTI(JVM Tool Interface)是所述Java虚拟机所提供的编程接口,提供了一套独立进程监控、获取目标Java虚拟机进程中Java对象的方法,而动态Instrumentation(执行容器)是Java的特性,其中通过使用Instrumentation,可以构建一个独立于应用程序的代理程序(Agent),用来监测和协助运行在JVM上的程序,并且能够替换和修改某些类的定义。
其中Java虚拟机(JVM)是一种抽象化的计算机,通过在实际的计算机上仿真模拟各种计算机功能来实现的,Java虚拟机有自己完善的硬体架构,如处理器、堆栈、寄存器等,还具有相应的指令系统,Java虚拟机屏蔽了与具体操作系统平台相关的信息,使得Java程序只需生成在Java虚拟机上运行的Java字节码,就可以在多种平台上不加修改地运行。
S102.从获取的所述Java类中,过滤出暴露目标API的类,所述目标API至少存在一个;
具体地,从所有的所述Java类中,通过调用Java中的方法,即通过调用class.getAnnotation(Controller.class)方法,过滤出所述暴露目标API的类,即过滤出并获取存在控制器类(Controller)注解的所述Java类。
其中,所述暴露目标API的类是指包含Controller注解的Java类,所述Controller注解是控制器类注解,而控制器类注解为Java的框架SpringMVC的标准注解,也就是说,采用SpringMVC框架开发的程序必须将API定义的方法写在含有控制器类注解的类中。
S103.从所述暴露目标API的类中过滤出所述暴露目标API的方法;
具体地,在步骤S103中,从所述暴露目标API的类中,通过调用Java中的方法,即通过调用class.getDeclaredMethods,过滤出所述暴露目标API的方法,即过滤并获取存在所述注解信息的所述暴露目标API的类的所有方法。
S104.从所述暴露目标API的方法中提取出参数信息以及注解信息;
具体地,从所述暴露目标API的方法中获取所述注解信息,即通过调用Method.getAnnotation()方法来获取所述注解信息,其中所述注解信息包括@RequestMapping@GetMapping@PostMapping@DeleteMapping和@PutMapping。
其中所述注解信息是Java的框架SpringMVC的标准注解,采用SpringMVC框架开发的程序必须要使用这套注解,以使得在该程序中的所述暴露目标API的方法能够暴露出目标API。
具体地,从所述暴露目标API的方法中提取出参数信息以及注解信息的具体实施方式可以包括:通过调用Java中的方法,即分别调用method.getParameters()、method.getParameterTypes()和method.getReturnType,分别获取所述暴露目标API的方法的所述参数信息,其中所述参数信息包括入参、入参类型和出参。
S105.将每一个目标API的注解信息与参数信息进行合并,生成所述每一个目标API预设的第一Java对象,并将所述第一Java对象存储至内存中;
具体地,将每一个目标API的注解信息与参数信息进行合并,生成所述每一个目标API预设的第一Java对象,并将所述第一Java对象存储至内存中的具体实施方式可以包括:将所述注解信息与所述参数信息进行合并并生成预设的第一Java对象,并将所述第一Java对象存储至内存中。举例而言,所述第一Java对象可以命名为SwaggerSpecification,所述第一Java对象所包含的信息最终将会在Swagger框架用于生成可视化的API文档。
S106.将所述第一Java对象转化成第一Json报文;
具体地,可以将所述第一Java对象通过序列化转化成针对Swagger框架的标准的第一Json报文,也就是说,所述Java对象以所述Json报文的形式保存。
S107.将所述第一Json报文导入Swagger框架以通过所述Swagger框架将所述第一Json报文转化成API文档。
具体地,可以通过Swagger框架中的Swagger-UI,导入所述Json报文后自动生成可视化的API文档。
参阅图2,示出了本发明另一实施例之生成API文档的方法的流程图。如图2所示,所述方法进一步可以包括以下步骤:
S201.在Java虚拟机中拦截接收到的服务请求;
具体地,在Java虚拟机中拦截接收到的服务请求的具体实施方式可以包括:通过调用Java中的方法,即在作为Java的SpringMVC框架中org.springframework.web.servlet.DispatcherServlet类的doDispatch方法运行和返回之前,在Java虚拟机中通过动态调整模块中的拦截方法来拦截所述请求。
其中doDispatch方法是SpringMVC框架中用于处理所有服务请求的总入口,而所述动态调整模块是所述方法中用于动态调整API文档的功能模块。
其中所述动态调整模块可以被命名为SwaggerAdapter。
S202.对所述服务请求进行解析,得到所述服务请求中包含的统一资源定位器信息(URL信息)、请求方法信息及请求头信息;
具体地,对所述服务请求进行解析,得到所述服务请求中包含的统一资源定位器信息、请求方法信息及请求头信息的具体实施方式可以包括:在拦截所述请求后,通过所述动态调整模块,解析所拦截所述请求的所述头信息、所述统一资源定位器信息和所述请求方法,其中URL是统一资源定位器,是万维网的统一资源定位标志,即指网络地址。
S203.从所述内存中找到与所述统一资源定位器信息、所述请求方法信息及所述请求头信息相对应的第二Java对象;
具体地,从所述内存中找到与所述统一资源定位器信息、所述请求方法信息及所述请求头信息相对应的第二Java对象的具体实施方式可以包括:其中在内存中存储Java对象时,不同的Java对象预先与对应的所述请求方法、所述统一资源定位器信息、所述头信息进行映射,后续在需要查找时,可以根据所述统一资源定位器信息、所述请求方法及所述请求头信息找到与所述第一Java对象相对应的所述第二Java对象。
其中,在内存中存储Java对象时,不同的Java对象预先与对应的所述请求方法、所述统一资源定位器信息、所述头信息进行映射,后续在需要查找时,可以根据所述统一资源定位器信息、所述请求方法及所述请求头信息找到与所述第一Java对象相对应的所述第二Java对象。
S204.根据所述请求头信息从所述服务请求中获取请求参数;
在一实施方式中,根据所述请求头信息从所述服务请求中获取请求参数的步骤可以包括:根据所述请求头信息中的内容类型(Content-Type)信息从所述服务请求中获取所述请求参数。
其中,Content-Type(内容类型)一般是指网页中存在的Content-Type,是Http协议的规范,用于标定请求传参的方式,定义网络文件的类型和网页的编码,决定浏览器将以什么形式、什么编码读取这个文件。
S205.根据所述请求参数与所述第二Java对象中的参数进行比较的比较结果,调整所述第二Java对象中的参数;
在一实施方式中,根据所述请求参数与所述第二Java对象中的参数进行比较的比较结果,调整所述第二Java对象中的参数的步骤可以包括:比较所述请求参数和所述Java对象的扫描出来的参数名(key)相同的话,则会被认定为是一个校验相同的字段(field),则在对应的所述Java对象中将相匹配的字段中标记为checked=true,其中所述标记作为一个预设数值,是所述Java对象的一个属性的值。
S206.将调整后的所述第二Java对象转化成新的Json报文。
在一示例性的实施方式中,所述生成API文档方法还包括:
获取用户预先设置的过滤条件,所述过滤条件包括所述预设数值对应的字段,与非预设数值对应的字段。
其中所述预设数值为对应的所述Java对象中将相匹配的字段中标记所取的值,例如所述预设数值为checked=true或checked=False。
在一实施方式中,所述将调整后的第二Java对象转化为新的Json报文包括:
将调整后的第二Java对象中满足所述过滤条件的字段过滤掉,得到过滤后的第二Java对象;
将过滤后的第二Java对象转化为新的Json报文。
具体地,在将调整后的所述第二Java对象转化成新的Json报文之前,允许用户通过客户端添加一个过滤条件,例如所述过滤条件为ignoreUncheckedField的参数,所述参数的值为true,以使得在转化成新的Json报文格式之前的所述第二Java对象会忽略掉不匹配的所述字段,也就是说,当在转化成所述Json报文之前的所述第二Java对象会过滤掉checked参数的值不为true的字段,然后转化为新的Json报文,以使得用新的Json报文通过所述Swagger框架生成的API文档根据实际运行的API信息来动态调整。
因此,所述生成API文档的方法不需要对于业务代码而言进行侵入式编写所述Swagger框架的注解来利用Swagger框架生成可视化的API文档,其中利用所述Swagger框架,只需要按照所述Swagger框架的规范去定义接口及接口相关的信息,再通过Swagger框架衍生出来的一系列项目和工具,就可以做到生成各种格式的API文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。
请参阅图3,示出了本发明实施例之一种生成API文档的系统300的程序模块示意图。所述生成API文档的系统300可以应用于计算机设备中,所述计算机设备可以是手机、平板个人计算机(tablet personal computer)、膝上型计算机(laptop computer)、等具有数据传输功能的设备。在本发明实施例中,生成API文档的系统300可以包括或被分割成一个或多个程序模块,一个或者多个程序模块被存储于可读存储介质中,并由一个或多个处理器所执行,以完成本发明实施例,并可实现上述生成API文档的系统300。本发明实施例所称的程序模块是指能够完成特定功能的一系列计算机程序指令段,比程序本身更适合于描述生成API文档的系统300在可读存储介质中的执行过程。在示例性的实施例中,该生成API文档的系统300包括获取模块301、第一过滤模块302、第二过滤模块303、抽取模块304、生成模块305、转化模块306、导入模块307。以下描述将具体介绍本发明实施例各程序模块的功能:
获取模块301,用于通过在Java虚拟机中加载预设的代理程序从Java虚拟机中运行的Java字节码中获取所有的Java类;
具体地,基于JVMTI机制,所述代理程序通过利用Instrumentation中的类加载器,也就是通过调用inst.getAllLoadedClasses()方法,从运行中的Java字节码中获取所有被加载到Java虚拟机运行的Java类。
其中所述JVMTI(JVM Tool Interface)是所述Java虚拟机所提供的编程接口,提供了一套独立进程监控、获取目标Java虚拟机进程中Java对象的方法,而动态Instrumentation(执行容器)是Java的特性,其中通过使用Instrumentation,可以构建一个独立于应用程序的代理程序(Agent),用来监测和协助运行在JVM上的程序,并且能够替换和修改某些类的定义。
其中Java虚拟机(JVM)是一种抽象化的计算机,通过在实际的计算机上仿真模拟各种计算机功能来实现的,Java虚拟机有自己完善的硬体架构,如处理器、堆栈、寄存器等,还具有相应的指令系统,Java虚拟机屏蔽了与具体操作系统平台相关的信息,使得Java程序只需生成在Java虚拟机上运行的Java字节码,就可以在多种平台上不加修改地运行。
第一过滤模块302,用于从获取的所述Java类中,过滤出暴露目标API的类,所述目标API至少存在一个;
具体地,从所有的所述Java类中,通过调用Java中的方法,即通过调用class.getAnnotation(Controller.class)方法,过滤出所述暴露目标API的类,即过滤出并获取存在控制器类(Controller)注解的所述Java类。
其中,所述暴露目标API的类是指包含Controller注解的Java类,所述Controller注解是控制器类注解,而控制器类注解为Java的框架SpringMVC的标准注解,也就是说,采用SpringMVC框架开发的程序必须将API定义的方法写在含有控制器类注解的类中。
第二过滤模块303,用于从所述暴露目标API的类中过滤出所述暴露目标API的方法;
具体地,在步骤S103中,从所述暴露目标API的类中,通过调用Java中的方法,即通过调用class.getDeclaredMethods,过滤出所述暴露目标API的方法,即过滤并获取存在所述注解信息的所述暴露目标API的类的所有方法。
抽取模块304,用于从所述暴露目标API的方法中提取出参数信息以及注解信息;
具体地,从所述暴露目标API的方法中获取所述注解信息,即通过调用Method.getAnnotation()方法来获取所述注解信息,其中所述注解信息包括@RequestMapping@GetMapping@PostMapping@DeleteMapping和@PutMapping。
其中所述注解信息是Java的框架SpringMVC的标准注解,采用SpringMVC框架开发的程序必须要使用这套注解,以使得在该程序中的所述暴露目标API的方法能够暴露出目标API。
具体地,从所述暴露目标API的方法中提取出参数信息以及注解信息的具体实施方式可以包括:通过调用Java中的方法,即分别调用method.getParameters()、method.getParameterTypes()和method.getReturnType,分别获取所述暴露目标API的方法的所述参数信息,其中所述参数信息包括入参、入参类型和出参。
生成模块305,用于将每一个目标API的注解信息与参数信息进行合并,生成所述每一个目标API预设的第一Java对象,并将所述第一Java对象存储至内存中;
具体地,将每一个目标API的注解信息与参数信息进行合并,生成所述每一个目标API预设的第一Java对象,并将所述第一Java对象存储至内存中的具体实施方式可以包括:将所述注解信息与所述参数信息进行合并并生成预设的第一Java对象,并将所述第一Java对象存储至内存中。举例而言,所述第一Java对象可以命名为SwaggerSpecification,所述第一Java对象所包含的信息最终将会在Swagger框架用于生成可视化的API文档。
转化模块306,用于将所述第一Java对象转化成第一Json报文;
具体地,可以将所述第一Java对象通过序列化转化成针对Swagger框架的标准的第一Json报文,也就是说,所述Java对象以所述Json报文的形式保存。
导入模块307,用于将所述第一Json报文导入Swagger框架以通过所述Swagger框架将所述第一Json报文转化成API文档。
具体地,可以通过Swagger框架中的Swagger-UI,导入所述Json报文后自动生成可视化的API文档。
在另一实施方式中,所述生成API文档的系统300还可以包括:拦截模块、解析模块、寻找模块、获参模块、调整模块及筛选模块。以下描述将具体介绍本发明实施例各程序模块的功能:
拦截模块,用于在Java虚拟机中拦截接收到的服务请求;
具体地,在Java虚拟机中拦截接收到的服务请求的具体实施方式可以包括:通过调用Java中的方法,即在作为Java的SpringMVC框架中org.springframework.web.servlet.DispatcherServlet类的doDispatch方法运行和返回之前,在Java虚拟机中通过动态调整模块中的拦截方法来拦截所述请求。
其中doDispatch方法是SpringMVC框架中用于处理所有服务请求的总入口,而所述动态调整模块是所述方法中用于动态调整API文档的功能模块。
其中所述动态调整模块可以被命名为SwaggerAdapter。
解析模块,用于对所述服务请求进行解析,得到所述服务请求中包含的统一资源定位器信息(URL信息)、请求方法信息及请求头信息;
具体地,对所述服务请求进行解析,得到所述服务请求中包含的统一资源定位器信息、请求方法信息及请求头信息的具体实施方式可以包括:在拦截所述请求后,通过所述动态调整模块,解析所拦截所述请求的所述头信息、所述统一资源定位器信息和所述请求方法,其中URL是统一资源定位器,是万维网的统一资源定位标志,即指网络地址。
寻找模块,用于从所述内存中找到与所述统一资源定位器信息、所述请求方法信息及所述请求头信息相对应的第二Java对象;
具体地,从所述内存中找到与所述统一资源定位器信息、所述请求方法信息及所述请求头信息相对应的第二Java对象的具体实施方式可以包括:其中在内存中存储Java对象时,不同的Java对象预先与对应的所述请求方法、所述统一资源定位器信息、所述头信息进行映射,后续在需要查找时,可以根据所述统一资源定位器信息、所述请求方法及所述请求头信息找到与所述第一Java对象相对应的所述第二Java对象。
其中,在内存中存储Java对象时,不同的Java对象预先与对应的所述请求方法、所述统一资源定位器信息、所述头信息进行映射,后续在需要查找时,可以根据所述统一资源定位器信息、所述请求方法及所述请求头信息找到与所述第一Java对象相对应的所述第二Java对象。
获参模块,用于根据所述请求头信息从所述服务请求中获取请求参数;
在一实施方式中,根据所述请求头信息从所述服务请求中获取请求参数的步骤可以包括:根据所述请求头信息中的内容类型(Content-Type)信息,通过调用预设方法从所述服务请求中获取所述请求参数。
可选地,通过调用所述预设方法request.getInputStream()和header["Content-Type"],解析所述请求头信息并获取所述请求参数。
其中,Content-Type(内容类型)一般是指网页中存在的Content-Type,是Http协议的规范,用于标定请求传参的方式,定义网络文件的类型和网页的编码,决定浏览器将以什么形式、什么编码读取这个文件。
调整模块,用于根据所述请求参数与所述第二Java对象中的参数进行比较的比较结果,调整所述第二Java对象中的参数;在一实施方式中,根据所述请求参数与所述第二Java对象中的参数进行比较的比较结果,调整所述第二Java对象中的参数的步骤可以包括:比较所述请求参数和所述Java对象的扫描出来的参数名(key)相同的话,则会被认定为是一个校验相同的字段(field),则在对应的所述Java对象中将相匹配的字段中标记为checked=true,其中所述标记作为一个预设数值,是所述Java对象的一个属性的值。
筛选模块,用于将调整后的所述第二Java对象转化成新的Json报文。
具体地,所述用于将调整后的所述第二Java对象转化成新的Json报文包括:获取用户预先设置的过滤条件,所述过滤条件包括所述预设数值对应的字段,与非预设数值对应的字段。
其中所述预设数值为对应的所述Java对象中将相匹配的字段中标记所取的值,例如所述预设数值为checked=true或checked=False。
在一实施方式中,所述将调整后的第二Java对象转化为新的Json报文包括:
将调整后的第二Java对象中满足所述过滤条件的字段过滤掉,得到过滤后的第二Java对象;
将过滤后的第二Java对象转化为新的Json报文。
具体地,在将调整后的所述第二Java对象转化成新的Json报文之前,允许用户通过客户端添加一个过滤条件,例如所述过滤条件为ignoreUncheckedField的参数,所述参数的值为true,以使得在转化成新的Json报文格式之前的所述第二Java对象会忽略掉不匹配的所述字段,也就是说,当在转化成所述Json报文之前的所述第二Java对象会过滤掉checked参数的值不为true的字段,然后转化为新的Json报文,以使得用新的Json报文通过所述Swagger框架生成的API文档根据实际运行的API信息来动态调整。
因此,所述生成API文档的方法不需要对于业务代码而言进行侵入式编写所述Swagger框架的注解来利用Swagger框架生成可视化的API文档,其中利用所述Swagger框架,只需要按照所述Swagger框架的规范去定义接口及接口相关的信息,再通过Swagger框架衍生出来的一系列项目和工具,就可以做到生成各种格式的API文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。
如图4所示,是本发明实施例之计算机设备400的硬件架构示意图。其中,计算机设备400可以是执行程序的智能手机、平板电脑、笔记本电脑、台式计算机、机架式服务器、刀片式服务器、塔式服务器或机柜式服务器(包括独立的服务器,或者多个服务器所组成的服务器集群)等。在本发明实施例中,所述计算机设备400是一种能够按照事先设定或者存储的指令,自动进行数值计算和/或信息处理的设备。如图所示,所述计算机设备400至少包括,但不限于,可通过装置总线相互通信连接存储器401、处理器402、网络接口403。其中:
本发明实施例中,存储器401至少包括一种类型的计算机可读存储介质,所述可读存储介质包括闪存、硬盘、多媒体卡、卡型存储器(例如,SD或DX存储器等)、随机访问存储器(RAM)、静态随机访问存储器(SRAM)、只读存储器(ROM)、电可擦除可编程只读存储器(EEPROM)、可编程只读存储器(PROM)、磁性存储器、磁盘、光盘等。在一些发明实施例中,存储器401可以是计算机设备400的内部存储单元,例如所述计算机设备400的硬盘或内存。在另一些发明实施例中,存储器401也可以是计算机设备400的外部存储设备,例如所述计算机设备400上配备的插接式硬盘,智能存储卡(Smart Media Card,SMC),安全数字(SecureDigital,SD)卡,闪存卡(Flash Card)等。当然,存储器401还可以既包括计算机设备400的内部存储单元也包括其外部存储设备。本发明实施例中,存储器401通常用于存储安装于计算机设备400的操作装置和各类应用软件,例如所述生成API文档的系统300的程序代码等。此外,存储器401还可以用于暂时地存储已经输出或者将要输出的各类数据。
处理器402在一些发明实施例中可以是中央处理器(Central Processing Unit,CPU)、控制器、微控制器、微处理器、或其他数据处理芯片。所述处理器402通常用于控制计算机设备400的总体操作。本发明实施例中,处理器402用于运行存储器401中存储的程序代码或者处理数据,例如运行所述生成API文档的系统300的程序代码,以实现上述实施例中的所述生成并动态调整方法。
所述网络接口403可包括无线网络接口或有线网络接口,所述网络接口403通常用于在所述计算机设备400与其他电子装置之间建立通信连接。例如,所述网络接口403用于通过网络将所述计算机设备400与外部终端相连,在所述计算机设备400与外部终端之间的建立数据传输通道和通信连接等。所述网络可以是企业内部网(Intranet)、互联网(Internet)、全球移动通讯装置(Global System of Mobile communication,GSM)、宽带码分多址(Wideband Code Division Multiple Access,WCDMA)、4G网络、5G网络、蓝牙(Bluetooth)、Wi-Fi等无线或有线网络。
值得一提的是,图4仅示出了具有部件401-403的计算机设备400,但是应理解的是,并不要求实施所有示出的部件,可以替代的实施更多或者更少的部件。
在本发明实施例中,存储于存储器401中的所述生成API文档的系统300还可以被分割为一个或者多个程序模块,所述一个或者多个程序模块被存储于存储器401中,并由一个或多个处理器(本发明实施例为处理器402)所执行,以完成本发明的所述所述生成API文档的方法。
本发明提供一种计算机可读存储介质,如闪存、硬盘、多媒体卡、卡型存储器(例如,SD或DX存储器等)、随机访问存储器(RAM)、静态随机访问存储器(SRAM)、只读存储器(ROM)、电可擦除可编程只读存储器(EEPROM)、可编程只读存储器(PROM)、磁性存储器、磁盘、光盘、服务器、App应用商城等等,其上存储有计算机程序,程序被处理器执行时实现相应功能。本发明实施例的计算机可读存储介质用于存储所述生成API文档的系统300,以被处理器执行时实现本发明的所述所述生成API文档的方法。
通过以上的实施方式的描述,本领域的技术人员可以清楚地了解到上述发明实施例方法可借助软件加必需的通用硬件平台的方式来实现,当然也可以通过硬件,但很多情况下前者是更佳的实施方式。
本领域的技术人员应理解,上述描述及附图中所示的本发明的实施例只作为举例而并不限制本发明。本发明的目的已经完整并有效地实现。本发明的功能及原理已在实施例中展示和说明,在没有背离所述原理下,本发明的实施方式可以有任何变形或修改。

Claims (10)

1.一种生成API文档的方法,其特征在于,包括以下步骤:
通过在Java虚拟机中加载预设的代理程序从所述Java虚拟机中运行的Java字节码中获取所有的Java类;
从获取的所述Java类中,过滤出暴露目标API的类,所述目标API至少存在一个;
从所述暴露目标API的类中过滤出所述暴露目标API的方法;
从所述暴露目标API的方法中提取出参数信息以及注解信息;
将每一个目标API的注解信息与参数信息进行合并,生成所述每一个目标API对应的第一Java对象,并将所述第一Java对象存储至内存中;
将所述第一Java对象转化成第一Json报文;
将所述第一Json报文导入Swagger框架以通过所述Swagger框架将所述第一Json报文转化成API文档。
2.根据权利要求1所述的方法,其特征在于,所述方法还包括:
在所述Java虚拟机中拦截接收到的服务请求;
得到所述服务请求中包含的统一资源定位器信息、请求方法信息及请求头信息;
从所述内存中找到与所述统一资源定位器信息、所述请求方法信息及所述请求头信息相对应的第二Java对象;
根据所述请求头信息从所述服务请求中获取请求参数;
将所述请求参数与所述第二Java对象中的参数进行比较,并按照比较结果调整所述第二Java对象中的参数;
将调整后的第二Java对象转化为新的Json报文。
3.根据权利要求2所述的方法,其特征在于,所述根据所述请求头信息从所述服务请求中获取请求参数包括:
根据所述请求头信息中的内容类型信息,通过调用预设方法从所述服务请求中获取请所述求参数信息。
4.根据权利要求2所述的方法,其特征在于,所述根据所述请求参数与所述第二Java对象中的参数进行比较的比较结果,调整所述第二Java对象中的参数,包括:
若所述比较结果为所述请求参数和所述第二Java对象的中的参数名相同,则将所述参数名对应的字段标记为预设数值,以在生成新的Json报文时保留所述字段。
5.根据权利要求4所述的方法,其特征在于,所述方法还包括:
获取用户预先设置的过滤条件,所述过滤条件包括所述预设数值对应的字段,与非预设数值对应的字段;
所述将调整后的第二Java对象转化为新的Json报文包括:
将调整后的第二Java对象中满足所述过滤条件的字段过滤掉,得到过滤后的第二Java对象;
将过滤后的第二Java对象转化为新的Json报文。
6.根据权利要求1至5任一项所述的方法,其特征在于,所述通过在Java虚拟机中加载预设的代理程序从所述Java虚拟机中运行的Java字节码中获取所有的Java类包括:
通过所述代理程序调用预设的类加载器,从所述Java虚拟机中运行的Java字节码中获取所有的Java类。
7.根据权利要求1至5任一项所述的方法,其特征在于,所述从获取的所述Java类中,过滤出暴露API的类包括:
通过调用所述Java中的方法,过滤出存在控制器类注解的Java类。
8.一种生成API文档的系统,其特征在于,包括:
获取模块,用于通过在Java虚拟机中加载预设的代理程序从所述Java虚拟机中运行的Java字节码中获取所有的Java类;
第一过滤模块,用于从获取的所述Java类中,过滤出暴露目标API的类,所述目标API至少存在一个;
第二过滤模块,用于从所述暴露目标API的类中过滤出所述暴露目标API的方法;
抽取模块,用于从所述暴露目标API的方法中提取出参数信息以及注解信息;
生成模块,用于将每一个目标API的注解信息与参数信息进行合并,生成所述每一个目标API对应的第一Java对象,并将所述第一Java对象存储至内存中;
转化模块,用于将所述第一Java对象转化成第一Json报文;
导入模块,用于将所述第一Json报文导入Swagger框架以通过所述Swagger框架将所述第一Json报文转化成API文档。
9.一种计算机设备,包括存储器以及处理器,所述存储器中存储有可在所述处理器上运行的计算机程序,其特征在于,所述处理器执行所述计算机程序时,实现如权利要求1至7任一项所述的方法的步骤。
10.一种计算机可读存储介质,所述计算机可读存储介质存储有计算机程序,其特征在于,所述计算机程序被处理器执行时实现如权利要求1至7任一项所述的方法的步骤。
CN202110568595.0A 2021-05-25 2021-05-25 生成api文档的方法、系统、设备及存储介质 Pending CN113296752A (zh)

Priority Applications (1)

Application Number Priority Date Filing Date Title
CN202110568595.0A CN113296752A (zh) 2021-05-25 2021-05-25 生成api文档的方法、系统、设备及存储介质

Applications Claiming Priority (1)

Application Number Priority Date Filing Date Title
CN202110568595.0A CN113296752A (zh) 2021-05-25 2021-05-25 生成api文档的方法、系统、设备及存储介质

Publications (1)

Publication Number Publication Date
CN113296752A true CN113296752A (zh) 2021-08-24

Family

ID=77324543

Family Applications (1)

Application Number Title Priority Date Filing Date
CN202110568595.0A Pending CN113296752A (zh) 2021-05-25 2021-05-25 生成api文档的方法、系统、设备及存储介质

Country Status (1)

Country Link
CN (1) CN113296752A (zh)

Cited By (2)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
CN113778883A (zh) * 2021-09-13 2021-12-10 湖南快乐阳光互动娱乐传媒有限公司 接口文档、测试和模拟生成方法和装置、计算机存储介质
CN113821254A (zh) * 2021-09-29 2021-12-21 平安普惠企业管理有限公司 接口数据处理方法、装置、存储介质及设备

Citations (10)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
CN103049271A (zh) * 2012-12-27 2013-04-17 微梦创科网络科技(中国)有限公司 自动生成api接口的描述文档的方法和装置
CN107967143A (zh) * 2017-12-14 2018-04-27 泰康保险集团股份有限公司 获取客户端应用程序源代码的更新指示信息的方法、装置和系统
CN108959076A (zh) * 2018-06-25 2018-12-07 浙江网新恒天软件有限公司 一种api在线调试方法
CN110162296A (zh) * 2019-04-15 2019-08-23 平安科技(深圳)有限公司 应用程序编程接口文档的生成方法、装置及终端设备
CN110471698A (zh) * 2019-07-29 2019-11-19 深圳数位传媒科技有限公司 Api文档的生成方法与装置、存储介质及计算机设备
CN110806863A (zh) * 2019-11-05 2020-02-18 泰康保险集团股份有限公司 接口文档生成方法及装置、电子设备、存储介质
CN110941950A (zh) * 2019-11-26 2020-03-31 北京明略软件系统有限公司 接口文档的生成方法、装置、服务器及存储介质
US20200274900A1 (en) * 2019-02-25 2020-08-27 Oracle International Corporation Automatic API Document Generation From SCIM Metadata
CN112199331A (zh) * 2020-10-09 2021-01-08 平安科技(深圳)有限公司 接口文档自动生成方法、系统、终端及存储介质
CN112463303A (zh) * 2020-12-01 2021-03-09 中国工商银行股份有限公司 Java虚拟机类加载方法及系统

Patent Citations (10)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
CN103049271A (zh) * 2012-12-27 2013-04-17 微梦创科网络科技(中国)有限公司 自动生成api接口的描述文档的方法和装置
CN107967143A (zh) * 2017-12-14 2018-04-27 泰康保险集团股份有限公司 获取客户端应用程序源代码的更新指示信息的方法、装置和系统
CN108959076A (zh) * 2018-06-25 2018-12-07 浙江网新恒天软件有限公司 一种api在线调试方法
US20200274900A1 (en) * 2019-02-25 2020-08-27 Oracle International Corporation Automatic API Document Generation From SCIM Metadata
CN110162296A (zh) * 2019-04-15 2019-08-23 平安科技(深圳)有限公司 应用程序编程接口文档的生成方法、装置及终端设备
CN110471698A (zh) * 2019-07-29 2019-11-19 深圳数位传媒科技有限公司 Api文档的生成方法与装置、存储介质及计算机设备
CN110806863A (zh) * 2019-11-05 2020-02-18 泰康保险集团股份有限公司 接口文档生成方法及装置、电子设备、存储介质
CN110941950A (zh) * 2019-11-26 2020-03-31 北京明略软件系统有限公司 接口文档的生成方法、装置、服务器及存储介质
CN112199331A (zh) * 2020-10-09 2021-01-08 平安科技(深圳)有限公司 接口文档自动生成方法、系统、终端及存储介质
CN112463303A (zh) * 2020-12-01 2021-03-09 中国工商银行股份有限公司 Java虚拟机类加载方法及系统

Non-Patent Citations (1)

* Cited by examiner, † Cited by third party
Title
半__夏: "利用swagger生成api接口文档", pages 1 - 4, Retrieved from the Internet <URL:https://blog.csdn.net/weixin_40149557/article/details/91182040> *

Cited By (2)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
CN113778883A (zh) * 2021-09-13 2021-12-10 湖南快乐阳光互动娱乐传媒有限公司 接口文档、测试和模拟生成方法和装置、计算机存储介质
CN113821254A (zh) * 2021-09-29 2021-12-21 平安普惠企业管理有限公司 接口数据处理方法、装置、存储介质及设备

Similar Documents

Publication Publication Date Title
CN108932122B (zh) 接口文档生成方法、装置、计算机设备和存储介质
CN108388515B (zh) 测试数据生成方法、装置、设备以及计算机可读存储介质
CN110688598B (zh) 业务参数采集方法、装置、计算机设备和存储介质
CN112015430A (zh) JavaScript代码翻译方法、装置、计算机设备及存储介质
CN110704521A (zh) 接口数据接入方法及系统
CN111061464B (zh) 解析代码生成方法、装置、设备及存储介质
CN113296752A (zh) 生成api文档的方法、系统、设备及存储介质
CN110795697A (zh) 逻辑表达式的获取方法、装置、存储介质以及电子装置
CN111797026A (zh) 测试用例生成方法、装置、计算机设备及存储介质
CN115794437A (zh) 微服务的调用方法、装置、计算机设备及存储介质
CN115599359A (zh) 一种代码生成方法、装置、设备及介质
CA3180833A1 (en) Flink sql statement verification method and device, computer equipment and storage medium
CN114186958A (zh) 将列表数据导出为电子表格的方法、计算设备及存储介质
CN113296785A (zh) 文档生成方法、系统、设备及可读存储介质
CN114637672A (zh) 自动化数据测试方法、装置、计算机设备及存储介质
CN114201215A (zh) 接口文档的生成方法、装置、电子设备及存储介质
CN109783134B (zh) 前端页面配置方法、装置及电子设备
US20150324333A1 (en) Systems and methods for automatically generating hyperlinks
CN115080596B (zh) 数据处理方法、装置、计算机设备及存储介质
CN111752600A (zh) 代码异常检测方法、装置、计算机设备及存储介质
CN111258586B (zh) 快应用运行、编译方法、装置、电子设备和存储介质
US11960560B1 (en) Methods for analyzing recurring accessibility issues with dynamic web site behavior and devices thereof
CN113553059B (zh) 局部变量查询方法、装置、服务器及存储介质
CN111338941B (zh) 信息处理方法和装置、电子设备和存储介质
CN110069297B (zh) 基于Spring MVC的异常处理方法、装置、计算机设备和存储介质

Legal Events

Date Code Title Description
PB01 Publication
PB01 Publication
SE01 Entry into force of request for substantive examination
SE01 Entry into force of request for substantive examination