# swagger-spring-boot **Repository Path**: battcn/spring-boot-starter-swagger ## Basic Information - **Project Name**: swagger-spring-boot - **Description**: swagger-spring-boot-starter 是一款建立在swagger基础之上的工具包,利用SpringBoot自动装配的特性,简化了传统swagger的繁琐配置 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 341 - **Forks**: 107 - **Created**: 2017-12-25 - **Last Updated**: 2025-04-21 ## Categories & Tags **Categories**: doc-tools, spring-boot-ext **Tags**: None ## README # 简介 # > 什么是 swagger? **`Swagger` 是一款自动生成在线文档 + 接口调试的工具。在 WEB 开发中不可否认的是我们需要给客户端提供 API 接口,这个时候需要借助 postman、rap 等工具 进行调试,以便于接口能正常交付给客户端人员,用过其它工具的应该知道一个 POST 请求一堆参数是非常枯燥且烦人的事情,而 swagger 就是让你摆脱这种束缚感....** > 项目群 **近期询问 `swagger-spring-boot-starter` 的朋友越来越多,所以就创建了一个意见反馈群(`QQ群:868804589`),BUG反馈和优化/美化的建议都可以在群里进行交流** > 源码地址 - GitHub:[https://github.com/battcn/swagger-spring-boot](https://github.com/battcn/swagger-spring-boot "https://github.com/battcn/swagger-spring-boot") - 码云:[https://gitee.com/battcn/spring-boot-starter-swagger/](https://gitee.com/battcn/spring-boot-starter-swagger/ "https://gitee.com/battcn/spring-boot-starter-swagger/") `swagger-spring-boot-starter` 是一款建立在`swagger`基础之上的工具包,利用SpringBoot自动装配的特性,简化了传统`swagger`的繁琐配置 > 项目介绍 - **`swagger-vue` :采用 Vue 编写的源代码,如果您对UI有更好的想法或者建议可以在该项目上进行扩展,它就是 UI 的源文件** - **`swagger-vue-ui` :编译后的纯 HTML 文件,如果你对 `swagger-spring-boot-starter` 包中的 UI 感到不满,你也可以选择排除 `swagger-vue-ui` 然后用第三方的...** - **`swagger-spring-boot-starter` : 自动装配 swagger 的扩展包** 有兴趣扩展自己的Starter包的可以参考文章:[编写自己的starter项目](http://blog.battcn.com/2017/07/13/springboot/springboot-starter-swagger/ "编写自己的starter项目") **如果该项目对您有帮助,欢迎Fork和Star,有疑问可以加 `QQ:1837307557`一起交流 ,如发现项目BUG可以提交`Issue`** # 使用 # **1.X 版本需要在启动类添加 `@EnableSwagger2Doc` 但是 2.X 版本后无需添加,请知晓...** - 在`pom.xml`中引入依赖: ``` xml com.battcn swagger-spring-boot-starter 2.1.5-RELEASE ``` > 中文乱码 如果遇到中文乱码,请确保自己的资源文件是 `UTF-8` 然后添加以下配置(一般情况只要自身环境正确,无需额外配置) ``` properties server.tomcat.uri-encoding=UTF-8 spring.http.encoding.force=true spring.http.encoding.enabled=true spring.http.encoding.charset=UTF-8 spring.messages.encoding=UTF-8 ``` > 访问 404 如果遇到 访问 `swagger-ui.html` 404 的问题,尝试如下方案 ``` java import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; /** * 解决 swagger-ui.html 访问路径 404 问题 * * @author Levin */ @Configuration public class SwaggerMvnConfiguration extends WebMvcConfigurationSupport { @Override protected void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**").addResourceLocations("classpath:/META-INF/resources/").setCachePeriod(0); } } ``` - 在`application.yml`中添加 ``` yaml spring: swagger: enabled: true ``` - 在`application.properties`中添加 ``` properties spring.swagger.enabled=true ``` # 更新记录 # ``` 2.1.5 发布时间:2019-03-04 更新内容: 1.修复当前 issues 2.新增接口搜索功能 3.优化VUE代码 4.最近在和公司前端大佬一起讨论代码重构和新版本UI渲染的问题, 同时2.1.5页是最稳定版本,届时没有BUG的情况下会重心在新版本研发 2.1.3 发布时间:2018-12-27 更新内容: 1.修复多层`content-path`时,路径404BUG 2.修复嵌套实体时,`@ApiModelProperty` 必填项显示错误 3.修复新版UI无缩进问题 4.修复接口过多情况下,未出现滚动条BUG 5.当接口类型是 `JAVA POJO`时,渲染的对象添加颜色区分 6.UI自适应优化,在不同分辨率下显示更加友好 7.UI兼容性优化,支持在IE11,EDGE等浏览器显示 8.致歉:近期较忙,所以发布周期延后,十分抱歉 2.1.2 发布时间:2018-11-14 更新内容: 1.解决调试面板 String 类型数据不显示 2.解决请求参数为 JSONObject时 没有按 JSON 传输 3.调试接口界面中 请求参数值可以添加 @ApiModelProperty 注解中 example 配置的默认值 2.1.1 发布时间:2018-11-08 更新内容: 1.调试面板JSON渲染美化 2.美化登陆页面UI 3.修复 TreeNode 数据结构导致内存溢出BUG 4.优化VUE的包目录结构和代码风格 2.1.0 发布时间:2018-09-22 更新内容: 1.调试面板JSON渲染美化 2.修复授权模式下任意密码可以登陆问题 3.修复ApiModelProperty#required 不生效问题 2.0.7 发布时间:2018-08-17 更新内容: 1.解决无请求参数无法调试,js报错 2.解决编辑 json 会导致 json 加一个双引号传输 2.0.6 发布时间:2018-07-25 更新内容: 1.解决请求错误时,异常信息不渲染的BUG 2.优化登陆保存策略 2.0.5 发布时间:2018-07-24 更新内容: 1.修复 spring.swagger.host 导致调试面板失效BUG 2.0.4 发布时间:2018-07-23 更新内容: 1.修改未自动注入BUG(在2.0.3中需要写明 ComponentScan) 2.0.2(具体效果看 samples-basic 中的项目示例) 2.0.3 发布时间:2018-07-17 更新内容: 1.UI美化 2.路由优化 3.文件上传控件美化 2.0.2(具体效果看 samples-basic 中的项目示例) 发布时间:2018年07月10日 更新内容: 1.UI添加响应结果 2.UI添加全局认证窗口 3.修复接口过多导致内存溢出泄露BUG 4.优化代码风格与标准 5.美化弹窗 6.添加安全验证过滤器(这样一来即使你想线上使用 swagger 一样可以) 7.登陆UI,保障接口安全 8.添加请求响应时间 9.升级Spring Boot 版本为 2.0.3-RELEASE 2.0.1 发布时间:2018年06月19日 更新内容: 1.重写UI 2.升级Spring Boot 为2.0.2 3.支持接口全局认证(设置一次 Token 需验证的地址自动将值写入到请求头/请求体中) 4.全局响应返回 5.支持可选的 Bean 验证插件; 由于日常开发中发现默认启动的验证插件扫描耗时比较久(由于我电脑弱,扫描时间大概在3-5秒...) 故而将插件修改为可选的,默认是关闭 6.支持选项卡切换 7.修复多余的斜杠 1.4.5 发布时间:2018年04月26日 更新内容: 1.解决配置 `context-path` 导致 `swagger-ui.html` 无法显示BUG 1.4.4 发布时间:2018年01月05日 更新内容: 1.优化选项卡切换 1.4.3 发布时间:2017年12月22日 更新内容: 1.修复CRUL口令 2.提升操作体验 1.4.2 发布时间:2017年12月15日 更新内容: 1.修复CRUL口令 2.渲染菜单列表颜色 1.4.1 发布时间:2017年12月13日 更新内容: 1.修复CRUL口令 2.修复DELETE类型请求部分存在404问题 1.4.0 发布时间:2017年12月14日 更新内容: 1.PATCH无法正确渲染 1.3.9 发布时间:2017年9月17日 更新内容: 1.修复对象深度拷贝 1.3.8 发布时间:2017年12月8日 更新内容: 1. 解决1.1.0发版中的bug 1.1.0 发布时间:2017年12月1日 更新内容: 1. 完成基础功能 ``` # 重写UI # > 操作风格 - 2.0.2 版本 ``` java # 2.0.3 版本新特性(开启后访问 swagger-ui.html 会自动路由到登陆页面,保障接口信息不被暴露) spring.swagger.security.filter-plugin=true # 配置账号密码 spring.swagger.security.username=battcn spring.swagger.security.password=battcn ``` ![接口说明](doc/img/2_4.png) > 操作风格 - 2.0.1 版本 ``` java # 配置 spring.swagger.api-key.key-name=myToken # 2.0.1 版本新特性 (支持可选的 Bean 验证插件) spring.swagger.validator-plugin=false # 定义全局响应返回 spring.swagger.global-response-messages.POST[0].code=400 spring.swagger.global-response-messages.POST[0].message=server response 400 spring.swagger.global-response-messages.POST[1].code=404 spring.swagger.global-response-messages.POST[1].message=server response 404 ``` ![接口说明](doc/img/2_1.png) ![接口说明](doc/img/2_2.png) ![接口说明](doc/img/2_3.png) > 操作风格 - 1.4.3支持 ![接口说明](doc/img/4.png) > 接口说明:折叠式Model ![接口说明](doc/img/1.png) > 接口说明:折叠式表单响应内容,告别长长的滚动条 ![接口说明](doc/img/2.png) > 在线调试 ![在线调试](doc/img/3.png) ## 配置说明 ## `spring.swagger.enabled`:提供该配置目的是方便多环境关闭,一般生产环境中不会暴露它,这时候就可以通过 `java -jar xx.jar --spring.swagger.enabled=false` 动态关闭,也可以在多环境配置写好 ### properties ### ``` spring.swagger.enabled=是否启用swagger,默认:true spring.swagger.title=标题 spring.swagger.description=描述信息 spring.swagger.version=版本 spring.swagger.license=许可证 spring.swagger.licenseUrl=许可证URL spring.swagger.termsOfServiceUrl=服务条款URL spring.swagger.contact.name=维护人 spring.swagger.contact.url=维护人URL spring.swagger.contact.email=维护人email spring.swagger.base-package=swagger扫描的基础包,默认:全扫描 spring.swagger.base-path=需要处理的基础URL规则,默认:/** spring.swagger.exclude-path=需要排除的URL规则,默认:空 spring.swagger.host=文档的host信息,默认:空 spring.swagger.globalOperationParameters[0].name=参数名 spring.swagger.globalOperationParameters[0].description=描述信息 spring.swagger.globalOperationParameters[0].modelRef=指定参数类型 spring.swagger.globalOperationParameters[0].parameterType=指定参数存放位置,参考ParamType:(header,query,path,body,form) spring.swagger.globalOperationParameters[0].required=指定参数是否必传,默认false #下面分组是 spring.swagger.groups..basePackage=swagger扫描的路径 #比如 spring.swagger.groups.基础信息.basePackage=com.battcn.controller.basic # 关闭 JSR spring.swagger.validator-plugin=false # 全局消息体 spring.swagger.global-response-messages.GET[0].code=400 spring.swagger.global-response-messages.GET[0].message=server response 400 spring.swagger.global-response-messages.POST[0].code=400 spring.swagger.global-response-messages.POST[0].message=server response 400 spring.swagger.global-response-messages.POST[1].code=404 spring.swagger.global-response-messages.POST[1].message=server response 404 ``` ### yaml ### 以下为 `application.yml` 配置示例 ``` yaml spring: swagger: enabled: true title: 标题 description: 描述信息 version: 系统版本号 contact: name: 维护者信息 base-package: swagger扫描的基础包,默认:全扫描(分组情况下此处可不配置) #全局参数,比如Token之类的验证信息可以全局话配置 global-operation-parameters: - description: 'Token信息,必填项' modelRef: 'string' name: 'Authorization' parameter-type: 'header' required: true groups: basic-group: base-package: com.battcn.controller.basic system-group: base-package: com.battcn.controller.system ``` # 贡献者 # Levin:1837307557@qq.com - 个人博文:[http://blog.battcn.com](http://blog.battcn.com "http://blog.battcn.com") _Rock:995269937@qq.com # 常用注解说明 # * `@Api`:一般用于Controller中,用于接口分组。(**`如:@Api(value = "用户接口", description = "用户接口", tags = {"1.1.0"})`** * `@ApiOperation`:接口说明,用于api方法上。(**`如: @ApiOperation(value = "用户查询", notes = "根据ID查询用户信息")`**) * `@ApiImplicitParam`:参数说明,适用于只有一个请求参数,主要参数 * `@ApiImplicitParams`:多个参数说明,主要参数参考上面`@ApiImplicitParam` * `@ApiModel`:实体类说明 * `@ApiModelProperty`:实体参数说明 # 如何参与 # 有兴趣的可以联系本人(Pull Request),参与进来一起开发,美化UI与配置项一起完善