swagger-spring-boot

Swagger Springboot

License

License

Categories

Categories

Spring Boot Container Microservices Swagger Program Interface REST Frameworks
GroupId

GroupId

com.purgeteam
ArtifactId

ArtifactId

swagger-spring-boot
Last Version

Last Version

0.2.0.RELEASE
Release Date

Release Date

Type

Type

pom
Description

Description

swagger-spring-boot
Swagger Springboot
Project URL

Project URL

https://github.com/purgeteam/swagger-spring-boot
Source Code Management

Source Code Management

https://github.com/purgeteam/swagger-spring-boot

Download swagger-spring-boot

How to add to project

<!-- https://jarcasting.com/artifacts/com.purgeteam/swagger-spring-boot/ -->
<dependency>
    <groupId>com.purgeteam</groupId>
    <artifactId>swagger-spring-boot</artifactId>
    <version>0.2.0.RELEASE</version>
    <type>pom</type>
</dependency>
// https://jarcasting.com/artifacts/com.purgeteam/swagger-spring-boot/
implementation 'com.purgeteam:swagger-spring-boot:0.2.0.RELEASE'
// https://jarcasting.com/artifacts/com.purgeteam/swagger-spring-boot/
implementation ("com.purgeteam:swagger-spring-boot:0.2.0.RELEASE")
'com.purgeteam:swagger-spring-boot:pom:0.2.0.RELEASE'
<dependency org="com.purgeteam" name="swagger-spring-boot" rev="0.2.0.RELEASE">
  <artifact name="swagger-spring-boot" type="pom" />
</dependency>
@Grapes(
@Grab(group='com.purgeteam', module='swagger-spring-boot', version='0.2.0.RELEASE')
)
libraryDependencies += "com.purgeteam" % "swagger-spring-boot" % "0.2.0.RELEASE"
[com.purgeteam/swagger-spring-boot "0.2.0.RELEASE"]

Dependencies

compile (1)

Group / Artifact Type Version
org.springframework.boot : spring-boot-configuration-processor Optional jar 2.1.7.RELEASE

Project Modules

  • swagger-spring-boot-starter

swagger-spring-boot

Maven Central License License License License

🔥 🔥 🔥 相关文档请访问 PurgeTeam docs 🔥 🔥 🔥

简介

可能大家都有用过swagger,可以通过ui页面显示接口信息,快速和前端进行联调。

现在基本都是多模块微服务化,每个服务都有这样的ui页面也是很不方便,swagger 也可以聚合在网关页面。

有开发过微服务的小伙伴应该体验过。当微服务模块多的情况下,每个模块都需要配置这样的一个类进行加载 swagger 。造成每个模块都存在大致一样的 SwaggerConfig ,极端的情况下,有些朋友复制其他模块的 SwaggerConfig 进行改造之后,发现仍然加载不出 swagger 的情况,造成明明是复制的,为何还加载不出,排查此bug极其费时间。

在此之上,可以构建出一个 swagger-starter 模块,只需要引用一个 jar ,加载一些特殊的配置,就可以快速地使用到 swagger 的部分功能了。

新特性

在原有 swagger 功能之上集成 knife4j

knife4jspringfox-swagger 的增强UI实现,为Java开发者在使用Swagger的时候,能拥有一份简洁、强大的接口文档体验。

该UI增强包主要包括两大核心功能:文档说明在线调试

文档说明: 根据Swagger的规范说明,详细列出接口文档的说明,包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息,使用swagger-bootstrap-ui能根据该文档说明,对该接口的使用情况一目了然。

在线调试: 提供在线接口联调的强大功能,自动解析当前接口参数,同时包含表单验证,调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息,帮助开发者在线调试,而不必通过其他测试工具测试接口是否正确,简介、强大。

功能使用

添加依赖

ps: 实际version版本请使用最新版 最新版本: Maven Central

点击查看最新新版本

<dependency>
  <groupId>com.purgeteam</groupId>
  <artifactId>swagger-spring-boot-starter</artifactId>
  <version>0.2.0.RELEASE</version>
</dependency>

配置swagger.properties文件

在自己项目模块的resources目录下 创建swagger.properties配置

swagger.basePackage="swagger扫描项目包路径"
swagger.title="swagger网页显示标题"
swagger.description="swagger网页显示介绍"

@EnableSwaggerPlugins注解。

@EnableSwaggerPlugins
@SpringBootApplication
public class FrontDemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(FrontDemoApplication.class, args);
  }

}

访问http://ip:端口/swagger-ui.html检查swagger-ui是否正常。

image.png

Zuul网关集成

做完上面步骤一个单体服务已经完成了 swagger 的配置。

集成到 zuul 网关上还需要配置其他的集成配置。

不过使用 swagger-spring-boot-starter 之后,流程变得很轻松。

只需要添加下面 @EnableSwaggerZuul 注解即可完成集成动作。

@EnableSwaggerZuul
@SpringBootApplication
public class ZuulApplication {

  public static void main(String[] args) {
    SpringApplication.run(ZuulApplication.class, args);
  }

}

访问http://ip:端口/swagger-ui.html检查swagger-ui是否正常。

image.png

状态支持

Select a spec 选择框里可以选择网关下的微服务列表进行聚合展示。

这里也支持了服务状态显示。

health > "用户服务"(user)
health > "认证服务"(auth)
sick > front-demo(已下线)
sick > giant-demo(已下线)

这里的 用户服务 认证服务 名称是根据相应服务的 swagger.properties 文件属性名 swagger.title 获取。

image.png

image.png

UI访问

访问地址: http://ip:端口/doc.html

image.png

可以访问基本ok。

全局token

新增 Authorize 全局 token

默认参数设置为了 Authorization 储存在 header, 如和自己的参数不一致请在 通用参数配置 设置。

knife4j-token.png

通用参数配置

通用参数配置是一个比较常用的功能,如 携带 token 访问接口。

postman 功能类似,解决 swagger 缺陷。

开启功能

路径: 文档管理/个性化设置

  • 启用Knife4j提供的增强功能
  • 开启动态请求参数

image.png

添加参数

路径: 文档管理/全局参数设置

添加 oauth2 token 值已自己登陆token 前缀记得添加 Bearer

参数名称: Authorization
参数值: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1ODI4MjYyNTIsInVzZXJfbmFtZSI6ImFkbWluIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9KSUFPU0UxIiwiUk9MRV9NRU1CRVJTIl0sImp0aSI6IjA3YWZjMDVhLWU3NjYtNDMxOC1iZGRmLWJkMWU4NTExOWU5MiIsImNsaWVudF9pZCI6InNzby1hdXRoLXNlcnZlciIsInNjb3BlIjpbInNlcnZlciJdfQ.LFMcZTXb0g4xTzRo8kVAwBbXe12-XRsYWJkHFBRCbWg

image.png

访问接口

需要登陆的接口 在请求头里会默认都添加有 Authorization

image.png

离线文档

Knife4j提供导出4种格式的离线文档(Html\Markdown\Word\Pdf)

路径: 文档管理/离线文档

image.png

总结

简单的starter代码编写可以减少新模块的复杂性,只需要简单的配置就可以使用相应的特性,减少复制代码不必要的错误。

示例代码地址:swagger-spring-boot

作者GitHub: Purgeyao 欢迎关注

qq交流群: 812321371 微信交流群: MercyYao

微信公众号:

微信公众号二维码

com.purgeteam

purgeteam

Springboot相关组件简化开发,微信交流群:MercyYao QQ交流群:812321371。Springboot peripherals to simplify development. WeChat ac group:MercyYao QQ ac group:812321371

Versions

Version
0.2.0.RELEASE
0.1.0.RELEASE