今天这篇文章介绍一下微服务如何聚合Swagger实现接口文档管理。

文章目录如下:

为什么需要聚合?

微服务模块众多,如果不聚合文档,则访问每个服务的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的配置其实很简单,分为如下部分:

  1. API文档基本信息配置
  2. 授权信息配置(基于OAuth2的认证配置)

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

代码如下:

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

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

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

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

案例源码已上传GitHub,关注VX:码猿技术专栏,回复关键:9529 获取!

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,关注VX:码猿技术专栏,回复关键:9529 获取!

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

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

API文档好用的功能介绍

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

1、搜索功能

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

2、离线文档

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

3、令牌配置

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

4、配置缓存

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

5、全局参数配置

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

总结

本篇文章介绍了微服务集成网关聚合Swagger文档,开发中非常实用。

微服务如何聚合 API 文档?这波秀~的更多相关文章

  1. 微服务系列之Api文档 swagger整合

    1.前言 微服务架构随之而来的前后端彻底分离,且服务众多,无论是前后端对接亦或是产品.运营翻看,一个现代化.规范化.可视化.可尝试的文档是多么重要,所以我们这节就说说swagger. Swagger是 ...

  2. 白话SpringCloud | 第十一章:路由网关(Zuul):利用swagger2聚合API文档

    前言 通过之前的两篇文章,可以简单的搭建一个路由网关了.而我们知道,现在都奉行前后端分离开发,前后端开发的沟通成本就增加了,所以一般上我们都是通过swagger进行api文档生成的.现在由于使用了统一 ...

  3. 微服务&#183;API文档

    阅文时长 | 3.92分钟 字数统计 | 2754.05字符 主要内容 | 1.什么是API文档 2.API文档的使用 3.声明与参考资料 『微服务·API文档』 编写人 | SCscHero 编写时 ...

  4. 互联网常见Open API文档资源

    原文地址:http://blog.sina.com.cn/s/blog_4d8713560100y272.html 所谓的开放API(OpenAPI)是服务型网站常见的一种应用,网站的服务商将自己的网 ...

  5. swagger在线api文档搭建指南,用于线上合适么?

    在上一篇文章中,我们讲解了什么是 api,什么是 sdk: https://www.cnblogs.com/tanshaoshenghao/p/16217608.html 今天将来到我们万丈高楼平地起 ...

  6. gateway聚合swagger3统一管理api文档

    springboot微服务整合swagger3方法很简单,下文会演示.但是在分布式项目中如果每个微服务都需要单独的分开访问获取接口文档就不方便了,本文将详细讲解springcloud gateway网 ...

  7. 添加swagger api文档到node服务

    swagger,一款api测试工具,详细介绍参考官网:http://swagger.io/ ,这里主要记录下怎么将swagger api应用到我们的node服务中: 1.任意新建node api项目, ...

  8. 微众api文档,身份证识别,ocr等人脸识别等

    https://cloud.tencent.com/document/product/655/14369 https://cloud.tencent.com/document/product/655/ ...

  9. spring cloud+dotnet core搭建微服务架构:Api网关(三)

    前言 国庆假期,一直没有时间更新. 根据群里面的同学的提问,强烈推荐大家先熟悉下spring cloud.文章下面有纯洁大神的spring cloud系列. 上一章最后说了,因为服务是不对外暴露的,所 ...

随机推荐

  1. Linux 使用 tail 命令查看文件内容

    使用方法: $ tail --help 用法:tail [选项]... [文件]... 以标准输出的形式打印文件的最后10行内容: 如果不指定文件,或者文件为"-",则从标准输入中 ...

  2. CSS基础-7 盒子模型大小

    在盒子模型当中,有些元素是影响盒子大小的. 首先border就会影响盒子的大小. 其次padding也会影响盒子的大小. 例子: .one { width:100px; height:100px; b ...

  3. [ vue ] 解耦vuex(按照组件来组织vuex的结构)

    问题描述 随着应用复杂度的增加,vuex用一个 store/index.js 文件来描述已经很难维护了,我们想把这些状态分割到单独文件里面. 参考1:https://vuex.vuejs.org/zh ...

  4. [ unittest ] 使用初体验

    import unittest from cal import Calculate class Mytest(unittest.TestCase): def setUp(self): self.cal ...

  5. Java Date 类型比较

    //某时间Date time = tRemind.getTime();//现在时间Date now = new Date();//结果大于0则是现在时间大于某时间//结果等于0则为刚好相等//结果小于 ...

  6. GORM学习指南

    orm是一个使用Go语言编写的ORM框架.它文档齐全,对开发者友好,支持主流数据库. 一.初识Gorm Github GORM 中文官方网站内含十分齐全的中文文档,有了它你甚至不需要再继续向下阅读本文 ...

  7. Hive的导入导出和常用过滤语句的学习

    原文: https://www.toutiao.com/i6769166601871688196/?group_id=6769166601871688196 数据的导入 load data [loca ...

  8. 修正了Model1模式,进入如今盛行的的Model2模式,也就是MVC模式

    注:图片如果损坏,点击文章链接:https://www.toutiao.com/i6513668601843548675/ 1.<JSP页面实际上就是Servlet> 2.<JSP页 ...

  9. C#进阶——记一次USB HID的各种坑(x86,x64,win10,win7)

    一.简叙 写工控上位机的搬砖人,难免会遇到USB通讯,在一个项目中,我写的上位机使用USB HID协议和STM32通讯传输数据,从零大概花了几天找例程,找资料,最后是各种搬砖修补,终于出来了一个出版D ...

  10. 【刷题-LeetCode】304. Range Sum Query 2D - Immutable

    Range Sum Query 2D - Immutable Given a 2D matrix matrix, find the sum of the elements inside the rec ...