微服务如何聚合 API 文档?聚合API使用教程

大雄 812 2022-09-05

下面是关于聚合 API|聚合API使用教程

为什么需要聚合?

微服务模块众多,如果不聚合文档,则访问每个服务的API文档都需要单独访问一个Swagger UI界面,这么做客户端能否接受?


反正作为强迫症的我是接受不了.......


既然使用了微服务,就应该有统一的API文档入口。


如何聚合?

统一的文档入口显然应该聚合到网关中,通过网关的入口统一映射到各个模块。




演示


本文采用Spring Cloud Gateway 聚合 Swagger 的 方式 生成API文档。


案例源码结构如下:




本文只介绍如何聚合Swagger,关于网关、注册中心等内容不再介绍,有不了解的看陈某前面文章。


单个服务如何聚合Swagger?

这里的单个服务不包括网关,网关需要单独配置。


单个服务聚合其实很简单,就是普通的Spring Boot 整合 Swagger,但是微服务模块众多,不能每个微服都整合一番,因此可以自定义一个swagger-starter,之后每个微服务都依赖这个starter即可。


详细的步骤如下:


1、创建swagger-starter

自定义starter这里就不再介绍了,都是基础的知识;


目录结构如下:




1、添加依赖


对于Swagger原生的UI界面陈某不太喜欢,因此使用了一款看起来还不错的UI界面,依赖如下:


<!--swagger-->

<dependency>

   <groupId>io.springfox</groupId>

   <artifactId>springfox-boot-starter</artifactId>

</dependency>

 

<!--swagger-ui  这里是用了一个好看一点ui界面-->

<dependency>

   <groupId>com.github.xiaoymin</groupId>

   <artifactId>swagger-bootstrap-ui</artifactId>

</dependency>

对于UI界面,每个人审美不同,选择自己喜欢的就好。


2、自动配置类配置Swagger


陈某是将每个服务的API信息抽离出一个属性类SwaggerProperties,后续只需要在每个服务的配置文件中指定即可。


@Data

@ConfigurationProperties(prefix = SwaggerProperties.PREFIX)

@Component

@EnableConfigurationProperties

public class SwaggerProperties {

    public static final String PREFIX="spring.swagger";

 

    //包

    private String basePackage;

 

    //作者相关信息

    private Author author;

 

    //API的相关信息

    private ApiInfo apiInfo;

 

    @Data

    public static class ApiInfo{

        String title;

        String description;

        String version;

        String termsOfServiceUrl;

        String license;

        String licenseUrl;

    }

    @Data

    public static class Author{

        private String name;

 

        private String email;

 

        private String url;

    }

}


对于Swagger的配置其实很简单,分为如下部分:


API文档基本信息配置


授权信息配置(基于OAuth2的认证配置)


API文档配置无非就是配置文档的基本信息,比如文档标题、作者、联系方式.....


代码如下:




授权信息配置也很简单,就是在全局信息的请求头中配置一个能够放置令牌的地方,代码如下:




此处对应UI界面的地方如下图:




只需要将获取token令牌设置到这里即可。


好了,swagger-starter关键代码就介绍完了,详细配置见源码。


案例源码已上传GitHub,关注公众号:码猿技术专栏,回复关键:9528 获取!


2、微服务引用swagger-starter

单个微服务引用就很简单了,只需要添加如下依赖:


<dependency>

  <groupId>cn.myjszl</groupId>

  <artifactId>swagger-starter</artifactId>

</dependency>

接下来只需要在配置文件配置API相关的信息即可,比如订单服务的配置如下:




好了,至此单个服务的配置完成了。


此时我们可以验证一下,直接访问:http://localhost:3002/swagger-order-boot/v2/api-docs,结果如下图:




网关如何聚合Swagger?

网关聚合的思想很简单,就是从路由中获取微服务的访问地址,然后拼接上 /v2/api-docs 即可。


同样的还是要添加Swagger的两个依赖,如下:


<!--swagger-->

<dependency>

   <groupId>io.springfox</groupId>

   <artifactId>springfox-boot-starter</artifactId>

</dependency>

 

<!--swagger-ui  这里是用了一个好看一点ui界面-->

<dependency>

   <groupId>com.github.xiaoymin</groupId>

   <artifactId>swagger-bootstrap-ui</artifactId>

</dependency>

创建GatewaySwaggerResourcesProvider实现SwaggerResourcesProvider,重写其中的get方法,代码如下:




案例源码已上传GitHub,关注公众号:码猿技术专栏,回复关键:9528 获取!


好了,网关的配置这里就完成了。


此时启动网关、订单、库存服务,直接访问网关的文档:http://localhost:3001/doc.html,结果如下图:




API文档好用的功能介绍

不得不说这款Swagger UI 界面还是比较简单易用的,个人用起来还不错。


1、搜索功能

在右上角的搜索功能可以根据接口描述搜索相关的接口信息,如下图:




2、离线文档

可以直接拷贝文档的MarkDown形式转换成Html或者PDF生成离线文档,如下图:




3、令牌配置

在访问需要认证的接口时,可以通过配置令牌,这样令牌将会全局生效,不必每个请求都要配置一遍,如下:




4、配置缓存

该文档的所有配置,包括请求参数、授权令牌等信息都是缓存的,也就是说配置一次,下次再打开的时候也是默认存在的。


5、全局参数配置

对于一些全局的参数,比如请求头中需要携带请求客户端、版本号等信息,可以在全局参数中配置,如下:

1.概述

该接口可以对设备上报的数值型数据点数据进行聚合,可以按小时/天/周/月对数据点数据进行求和/平均值/最大值/最小值进行聚合。一次可以获取多个数据点的聚合数据。
要使用该接口,必须先请求开通该接口。请求通过的之后上报的数据才会进行聚合运算。
使用例子,如:智能水表的用水量数据点,可以统计分析每户每个月的用水量、每个星期的用水量和每天的用水量。从而,形成一个月报表、周报表和天报表。

2.Open API的高级数据接口使用流程

Open API的高级数据接口,就是获取设备聚合数据。
当客户已开通open API聚合接口使用权限后,就可以调用该接口进行设备上报的数值型数据点数据进行聚合分析,可以按小时/天/周/月对数据点数据进行求和/平均值/最大值/最小值进行聚合。

2.1创建用户

http://swagger.gizwits.com/doc/index/openapi_apps#/用户管理/post_app_users
如下图为创建匿名登录
Alt text

2.2.登录用户

匿名创建接口和匿名登录接口一样。

2.3.绑定设备

http://swagger.gizwits.com/doc/index/openapi_apps#/绑定管理/post_app_bind_mac
Alt text

2.4.上报设备数据

使用机智云提供的xpg工具,通过模拟mcu上报当前设备的数据。
工具的使用方法如下:
http://docs.gizwits.com/zh-cn/deviceDev/串口工具使用文档.html
Alt text

2.5.数据聚合查询

http://swagger.gizwits.com/doc/index/openapi_apps#/高级数据接口
Alt text

查询后的结果:
Alt text

3.企业API的设备数据聚合查询流程

设备数据聚合查询只是对单台设备进行数据聚合查询,该接口提供查询某个时间周期内某个WiFi设备数据型数据点的聚合运算,包括求和、平均、最大、最小。
注意:企业API使用先向机智云技术申请开通企业API,以及要在API配置处添加IP白名单。

3.1.申请开通企业API

申请开通企业API的流程:
http://docs.gizwits.com/zh-cn/Cloud/ent_dev.html

3.2.添加IP白名单

Alt text
IP为你当前服务器的外部IP。
Alt text

3.3.申请开通企业API聚合接口使用

联系机智云技术人员,向他们申请开通企业API聚合接口的使用权限。

3.4.获取token

请求URL:
http://enterpriseapi.gizwits.com/v1/products/447c947fff3245a18dfc709371c34e69/access_token
Body参数填写:
{
“enterprise_id”: “string”,
“enterprise_secret”: “ string “,
“product_secret”: “ string “
}
Alt text
注意:不能在swagger上面直接请求,因为swagger服务的IP没有在你们的IP白名单内,如果你暂时还没有搭建好后台服务器,可以借用chrome浏览器插件postman来进行请求。

3.5.上报设备状态

Alt text

3.6.调用单台设备数据聚合查询接口

请求URL:
http://enterpriseapi.gizwits.com/v1/products/cdfb1e7f2d31474ca10396de88491372/devices/Zb248887fhMVZ2V2Jhz2xfq/agg_data?start_ts=1485151200000&end_ts=1485153000000&attrs=t1%2Ct2%2Ct3%2Ct4&aggregator=avg&unit=HOURS
URL的Params值有:
product_key
did
start_ts
end_ts
attrs
aggregator
unit

Headers参数:
Authorize token “填token”
Content-Type application/json

Alt text

注意:${token值}是不包括${}号,只需将从获取token接口获得token值放到token之后。例如:Authorization: token efbekskdklllsF

以上就是小编为大家整理的聚合 API|聚合API使用教程

版权声明:本文内容由网络用户投稿,版权归原作者所有,本站不拥有其著作权,亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容,请联系我们jiasou666@gmail.com 处理,核实后本网站将在24小时内删除侵权内容。

上一篇:ASP.NET Identity详解
下一篇:极速数据API授权文档与无代码连接方式,全国省市县行政区划分
相关文章

 发表评论

暂时没有评论,来抢沙发吧~