CN111158664B - 一种Swagger接口文档工具及其使用方法 - Google Patents

Abstract

本发明涉及一种Swagger接口文档工具及其使用方法，该工具包括扫描模块、处理模块、展示模块、测试模块，所述扫描模块、展示模块、测试模块分别与处理模块连接；该使用方法先通过扫描模块，扫描语言中有关接口信息的部分及额外的扩展信息；再通过处理模块，对所有信息进行梳理、筛选、定义、重组，组织处理该产品可识别的信息；然后，通过展示模块，将整理出的信息通过页面的方法展现出来；使用者通过测试模块能进行测试；本发明彻底脱离java业务代码限制，不再和业务代码或系统有任何的牵连，不再有现有技术中存在的安全问题，同时，页面友好、易用，保留足够的扩展性，能够适应多样的接口验证限制，彻底提高软件开发效率，是真正的软件生产力工具。

Description

一种Swagger接口文档工具及其使用方法

技术领域

本发明涉及Java开发技术领域，具体地说是一种Swagger接口文档工具及其使用方法。

背景技术

Swagger的目标是为RESTAPIs定义一个标准的，与语言无关的接口，使人和计算机在看不到源码、看不到文档或者不能通过网络流量检测的情况下，能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑，类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

在Java开发领域中，服务调用时，需要悉知接口的所有信息，接口的对接也只是软件开发中的一个步骤。但是目前现有的技术，都是将接口开发文档发布到实际的生产环境中，导致生产环境的冗余和不安全性，同时也占用了一定的硬件资源，这部分资源其实就是完全的被浪费掉了。

现有的Swagger使用不够方便，对语言的侵入性很高；现有Swagger的页面不够友好，使用困难，扩展性不够；现有的Swagger对接口进行调试时，能力有限，不能完全的使用接口验证。

因此，如何提供一种Swagger接口文档工具及其使用方法，以避免生产环境的冗余，降低不安全性，减少占用硬件资源，避免资源浪费，使用方便，扩展性好，能够使用多样的接口验证，是目前本领域技术人员亟待解决的技术问题。

发明内容

有鉴于此，本申请的目的在于提供一种Swagger接口文档工具及其使用方法，以避免生产环境的冗余，降低不安全性，减少占用硬件资源，避免资源浪费，使用方便，扩展性好，能够使用多样的接口验证。

为了达到上述目的，本申请提供如下技术方案。

采用的第一种技术方案：一种Swagger接口文档工具，包括扫描模块、处理模块、展示模块、测试模块，所述扫描模块、展示模块、测试模块分别与所述处理模块连接。

优选地，所述扫描模块包括关键字搜索和字段搜索模块；

所述关键字搜索是对web框架的restful接口关键字进行搜索；

所述字段搜索模块是基于java反射机制的原生字段进行搜索。

优选地，所述处理模块包括分析模块、组织模块、存储模块及索引模块。

优选地，所述分析模块为代码注释分析，所述组织模块为对主体数据进行组织，所述存储模块为B+树数据结构，所述索引模块为B+树构建数据。

优选地，所述展示模块是采用Web页面展示服务的方式，所述测试模块是采用接口模拟Http测试的方式。

采用的第二种技术方案：一种Swagger接口文档工具的使用方法，包括以下步骤：

101、先通过扫描模块，扫描语言中有关接口信息的部分，以及额外的一些扩展信息；

102、通过处理模块，对所有信息进行梳理、筛选、定义、重组，组织处理该产品可识别的信息；

103、通过展示模块，将整理出的信息通过页面的方法展现出来；

104、使用测试模块，使用者能进行测试。

优选地，所述步骤101包括以下步骤：

201、根据现有的web服务框架的支持，识别出其中的restful接口关键字，确定该http的可识别接口；

202、扫描出并且定位到restful接口方法，进行参数属性的扫描，获取到参数属性信息，并准确的获取到参数的类型；

203、使用代码注释的方式，对代码注释进行扫描，扫描出相关的注解关键字，并将这些注释关键字转换成配置项。

优选地，所述步骤102包括以下步骤：

301、将获取到的接口信息、参数信息、及注释配置信息重新组织成一个完整的对象；

302、使用B+树的数据接口对数据进行存储，以接口的class类作为根节点，接口信息作为子节点数据；

303、在B+树数据结构的基础上，再添加索引机制，同样使用B+树的数据接口，以接口信息作为根节点，接口信息作为子节点，使查询效率更快。

优选地，所述展示模块是以使用web服务的形式展示给使用者。

优选地，所述测试模块包括以下步骤：用户只需要按照页面的提示填写相关的数据，并点击请求按钮，即可完成一次接口模拟测试，产品会把接口结果展示在在页面上。

本发明所获得的有益技术效果：

1)本发明克服了现有swagger所存在的缺陷，本发明彻底脱离java业务代码限制，不再和业务代码或系统有任何的牵连，不再有现有技术中存在的安全问题，同时，页面友好、易用，保留足够的扩展性，能够适应多样的接口验证限制，彻底提高软件开发效率，是真正的软件生产力工具；

2)本发明通过对语言的扫描，直接获取信息，也不对现有代码有任何的侵入性；通过重新架构产品的定义，把页面不够友好、使用困难及扩展性不够等缺陷都避免掉，方面使用，结构明显，扩展性良好；通过扫描足够的信息，把接口的信息全部展现出来，并且能够实时的调用接口，把接口信息展现出来，能够使用多样的接口验证。

上述说明仅是本申请技术方案的概述，为了能够更清楚了解本申请的技术手段，从而可依照说明书的内容予以实施，并且为了让本申请的上述和其他目的、特征和优点能够更明显易懂，以下以本申请的较佳实施例并配合附图详细说明如后。

根据下文结合附图对本申请具体实施例的详细描述，本领域技术人员将会更加明了本申请的上述及其他目的、优点和特征。

附图说明

为了更清楚地说明本申请实施例或现有技术中的技术方案，下面将对实施例或现有技术描述中所需要使用的附图作简单地介绍，显而易见地，下面描述中的附图是本申请的一些实施例，对于本领域普通技术人员来讲，在不付出创造性劳动的前提下，还可以根据这些附图获得其他的附图。在所有附图中，类似的元件或部分一般由类似的附图标记标识。附图中，各元件或部分并不一定按照实际的比例绘制。

图1是本公开一种实施例中Swagger接口文档工具的结构示意图；

图2是本公开一种实施例中Swagger接口文档工具使用方法的流程图。

具体实施方式

为使本申请实施例的目的、技术方案和优点更加清楚，下面将结合本申请实施例中的附图，对本申请实施例中的技术方案进行清楚、完整地描述，显然，所描述的实施例是本申请一部分实施例，而不是全部的实施例。在下面的描述中，提供诸如具体的配置和组件的特定细节仅仅是为了帮助全面理解本申请的实施例。因此，本领域技术人员应该清楚，可以对这里描述的实施例进行各种改变和修改而不脱离本申请的范围和精神。另外，为了清楚和简洁，实施例中省略了对已知功能和构造的描述。

应该理解，说明书通篇中提到的“一个实施例”或“本实施例”意味着与实施例有关的特定特征、结构或特性包括在本申请的至少一个实施例中。因此，在整个说明书各处出现的“一个实施例”或“本实施例”未必一定指相同的实施例。此外，这些特定的特征、结构或特性可以任意适合的方式结合在一个或多个实施例中。

此外，本申请可以在不同例子中重复参考数字和/或字母。这种重复是为了简化和清楚的目的，其本身并不指示所讨论各种实施例和/或设置之间的关系。

本文中术语“和/或”，仅仅是一种描述关联对象的关联关系，表示可以存在三种关系，例如，A和/或B，可以表示：单独存在A，单独存在B，同时存在A和B三种情况，本文中术语“/和”是描述另一种关联对象关系，表示可以存在两种关系，例如，A/和B，可以表示：单独存在A，单独存在A和B两种情况，另外，本文中字符“/”，一般表示前后关联对象是一种“或”关系。

本文中术语“至少一种”，仅仅是一种描述关联对象的关联关系，表示可以存在三种关系，例如，A和B的至少一种，可以表示：单独存在A，同时存在A和B，单独存在B这三种情况。

还需要说明的是，在本文中，诸如第一和第二等之类的关系术语仅仅用来将一个实体或者操作与另一个实体或操作区分开来，而不一定要求或者暗示这些实体或操作之间存在任何这种实际的关系或者顺序。而且，术语“包括”、“包含”或者其任何其他变体意在涵盖非排他性的包含。

实施例1

如附图1所示，一种Swagger接口文档工具，包括扫描模块、处理模块、展示模块、测试模块，所述扫描模块、展示模块、测试模块分别与所述处理模块连接。

所述扫描模块包括关键字搜索和字段搜索模块。

所述关键字搜索是对web框架的restful接口关键字进行搜索。

所述字段搜索模块是基于java反射机制的原生字段进行搜索。

所述处理模块包括分析模块、组织模块、存储模块及索引模块。

所述分析模块为代码注释分析，所述组织模块为对主体数据进行组织，所述存储模块为B+树数据结构，所述索引模块为B+树构建数据。

所述展示模块是采用Web页面展示服务的方式，所述测试模块是采用接口模拟Http测试的方式。

实施例2

基于上述实施例1，如附图2所示，一种Swagger接口文档工具的使用方法，包括以下步骤：

101、先通过扫描模块，扫描语言中有关接口信息的部分，以及额外的一些扩展信息。

具体包括以下步骤：

201、根据现有的web服务框架的支持，识别出其中的restful接口关键字，确定该http的可识别接口。

例如，根据spring mvc框架的支持，可以识别出其中的restful接口关键字，例如GetMapping、PostMapping、DeleteMapping、PutMapping等关键字，使其可以确定该http的可识别接口。

202、扫描出并且定位到restful接口方法，进行参数属性的扫描，获取到参数属性信息，使用java反射机制，准确的获取到参数的类型。

203、使用代码注释的方式，对代码注释进行扫描，扫描出相关的注解关键字，例如，@jpRequestRequiredParam、@jpRequestOptionParam、@jpSummary、@jpDesc、@jpConsumes、@jpReturnDesc、@jpTag，并将这些注释关键字转换成配置项。

102、通过处理模块，对所有信息进行梳理、筛选、定义、重组，组织处理该产品可识别的信息。

具体包括以下步骤：

301、将获取到的接口信息、参数信息、及注释配置信息重新组织成一个完整的对象；

302、使用B+树的数据接口对数据进行存储，以接口的class类作为根节点，接口信息作为子节点数据，以解决因接口数据量比较大，会导致信息查询较慢的问题。

303、在B+树数据结构的基础上，再添加索引机制，同样使用B+树的数据接口，以接口信息作为根节点，接口信息作为子节点，使查询效率更快。

103、通过展示模块，将整理出的信息通过页面的方法展现出来。

其中，展示模块是以使用web服务的形式展示给使用者，web页面会将该接口的参数模型以可视化的方式展现出来。

104、使用测试模块，使用者能进行测试。

其中，测试模块包括以下步骤：用户只需要按照页面的提示填写相关的数据，并点击请求按钮，即可完成一次接口模拟测试，接口文档工具会把接口结果展示在在页面上。该测试相比于其他的Http工具，例如PostMan,更加的可视化，测试人员不需要关注接口url、请求方式、请求头信息等等，只需要关注业务参数而已，该接口文档工具把业务和接口本身从逻辑上区分开来，使用者更注重业务信息，从而弱化接口信息。

该发明克服了现有swagger所存在的缺陷，本发明彻底脱离java业务代码限制，不再和业务代码或系统有任何的牵连，不再有现有技术中存在的安全问题，同时，页面友好、易用，保留足够的扩展性，能够适应多样的接口验证限制，彻底提高软件开发效率，是真正的软件生产力工具；通过对语言的扫描，直接获取信息，也不对现有代码有任何的侵入性；通过重新架构产品的定义，把页面不够友好、使用困难及扩展性不够等缺陷都避免掉，方面使用，结构明显，扩展性良好；通过扫描足够的信息，把接口的信息全部展现出来，并且能够实时的调用接口，把接口信息展现出来，能够使用多样的接口验证。

以上所述仅为本发明的优选实施例而已，其并非因此限制本发明的保护范围，对于本领域的技术人员来说，本发明可以有各种更改和变化。凡在本发明的精神和原则之内，通过常规的替代或者能够实现相同的功能在不脱离本发明的原理和精神的情况下对这些实施例进行变化、修改、替换、整合和参数变更均落入本发明的保护范围内。

Claims (7)

1.一种Swagger接口文档工具，其特征在于，包括扫描模块、处理模块、展示模块、测试模块，所述扫描模块、展示模块、测试模块分别与所述处理模块连接；

所述扫描模块包括关键字搜索和字段搜索模块；

所述关键字搜索是对web框架的restful接口关键字进行搜索；

所述字段搜索模块是基于java反射机制的原生字段进行搜索；

所述处理模块包括分析模块、组织模块、存储模块及索引模块；

所述分析模块为代码注释分析，所述组织模块为对主体数据进行组织，所述存储模块为B+树数据结构，所述索引模块为B+树构建数据。

2.根据权利要求1所述的Swagger接口文档工具，其特征在于，所述展示模块是采用Web页面展示服务的方式，所述测试模块是采用接口模拟http测试的方式。

3.根据权利要求1-2任一项所述Swagger接口文档工具的使用方法，其特征在于，包括以下步骤：

101、先通过扫描模块，扫描语言中有关接口信息的部分，以及额外的一些扩展信息；

102、通过处理模块，对所有信息进行梳理、筛选、定义、重组，组织处理Swagger接口文档工具可识别的信息；

103、通过展示模块，将整理出的信息通过页面的方法展现出来；

104、使用测试模块，使用者能进行测试。

4.根据权利要求3所述Swagger接口文档工具的使用方法，其特征在于，所述步骤101包括以下步骤：

201、根据现有的web服务框架的支持，识别出其中的restful接口关键字，确定该http的可识别接口；

202、扫描出并且定位到restful接口方法，进行参数属性的扫描，获取到参数属性信息，并准确的获取到参数的类型；

203、使用代码注释的方式，对代码注释进行扫描，扫描出相关的注解关键字，并将这些注释关键字转换成配置项。

5.根据权利要求4所述Swagger接口文档工具的使用方法，其特征在于，所述步骤102包括以下步骤：

301、将获取到的接口信息、参数信息、及注释配置信息重新组织成一个完整的对象；

302、使用B+树的数据接口对数据进行存储，以接口的class类作为根节点，接口信息作为子节点数据；

303、在B+树数据结构的基础上，再添加索引机制，同样使用B+树的数据接口，以接口信息作为根节点，接口信息作为子节点，使查询效率更快。

6.根据权利要求5所述Swagger接口文档工具的使用方法，其特征在于，所述展示模块是以使用web服务的形式展示给使用者。

7.根据权利要求5所述Swagger接口文档工具的使用方法，其特征在于，所述测试模块包括以下步骤：用户只需要按照页面的提示填写相关的数据，并点击请求按钮，即可完成一次接口模拟测试，Swagger接口文档工具会把接口结果展示在在页面上。