聊一聊Swagger-UI的那些事情

清疚 2022-12-22 09:45 137阅读 0赞

# 软件简介 #

Swagger是一个实现了OpenAPI(OpenAPI Specification)规范的工具集。OpenAPI是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，  
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。  
随着前后端的技术划分，对接口的规范以及测试要求也越来越高，因此现市面上同时出现好几款开源对Swagger 的功能优化，包括皮肤、功能等优化。下面我们聊聊流行的Swagger UI，包括有

*  Swagger 原生UI
 *  Bootstrap-ui Bootstrap的UI
 *  Knife4j Bootstrap的升级版的UI

# Swagger 原生 #

## 简介 ##

Swagger UI是HTML，Javascript和CSS资产的集合，可以从符合OAS标准的API动态生成漂亮的文档

## 集成Jar ##

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
         
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
         
        <version>2.9.2</version>
    </dependency>

## 效果图 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2VsdmlzaGVoYWk_size_16_color_FFFFFF_t_70_pic_center]

# Bootstrap-ui Bootstrap的UI #

## 简介 ##

Swagger-bootstrap-ui在满足原Swagger-ui功能的同时，还提供了文档的增强功能，这些功能是官方Swagger-ui所没有的，每一个增强的功能都是贴合实际,考虑到开发者的实际开发需要,是比不可少的功能，主要包括：

*  个性化配置：通过个性化ui配置项，可自定义UI的相关显示信息
 *  离线文档：根据标准规范，生成的在线markdown离线文档，开发者可以进行拷贝生成markdown接口文档，通过其他第三方markdown转换工具转换成html或pdf，这样也可以放弃swagger2markdown组件
 *  接口排序：自1.8.5后，ui支持了接口排序功能，例如一个注册功能主要包含了多个步骤,可以根据swagger-bootstrap-ui提供的接口排序规则实现接口的排序，step化接口操作，方便其他开发者进行接口对接

## 集成Jar ##

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        
        <version>2.9.2</version>
    </dependency>
    <dependency>
    	<groupId>com.github.xiaoymin</groupId>
    	<artifactId>swagger-bootstrap-ui</artifactId>
    	
    	<version>1.9.3</version>
    </dependency>

## 效果图![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2VsdmlzaGVoYWk_size_16_color_FFFFFF_t_70_pic_center 1] ##

# Knife4j Bootstrap的升级版的UI #

## 简介 ##

作者一开始项目初衷是为了写一个增强版本的Swagger 前端UI,但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在Swagger-bootstrap-ui的1.8.5~1.9.6版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。  
因此,项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.

Swagger-bootstrap-ui的所有特性都会集中在knife4j-spring-ui包中,并且后续也会满足开发者更多的个性化需求.

## 集成Jar ##

maven中的pom.xml增加依赖

<dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        
        <version>2.0.4</version>
    </dependency>

[参考文档][Link 1]

## 效果图 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2VsdmlzaGVoYWk_size_16_color_FFFFFF_t_70_pic_center 2]  
5、其他  
欢迎有问题及时交流~  
以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多交流,  
另各老铁们都在用其它的那个Swagger-UI了，还是有其它的？？？欢迎一起分享

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2VsdmlzaGVoYWk_size_16_color_FFFFFF_t_70_pic_center]: /images/20221120/0630edcff60d49658b72af9601a74d47.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2VsdmlzaGVoYWk_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221120/e581c9ad5df0487c9efbdd9f24be790e.png
[Link 1]: https://doc.xiaominfo.com/guide/useful.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2VsdmlzaGVoYWk_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20221120/205e5a40fddc42b4b46187d1835a6e2e.png