{"id":15019351,"url":"https://github.com/battcn/swagger-spring-boot","last_synced_at":"2025-04-05T18:07:54.596Z","repository":{"id":57717694,"uuid":"112716404","full_name":"battcn/swagger-spring-boot","owner":"battcn","description":"swagger-spring-boot-starter 是一款建立在swagger基础之上的工具包，利用SpringBoot自动装配的特性，简化了传统swagger的繁琐配置","archived":false,"fork":false,"pushed_at":"2020-01-15T09:44:59.000Z","size":4792,"stargazers_count":444,"open_issues_count":21,"forks_count":124,"subscribers_count":48,"default_branch":"master","last_synced_at":"2024-10-29T18:11:16.334Z","etag":null,"topics":["jdk","springboot","swagger"],"latest_commit_sha":null,"homepage":"","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/battcn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-01T08:45:39.000Z","updated_at":"2024-08-03T20:22:49.000Z","dependencies_parsed_at":"2022-09-09T09:31:01.015Z","dependency_job_id":null,"html_url":"https://github.com/battcn/swagger-spring-boot","commit_stats":null,"previous_names":["battcn/swagger-spring-boot-starter","battcn/spring-boot-starter-swagger"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/battcn%2Fswagger-spring-boot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/battcn%2Fswagger-spring-boot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/battcn%2Fswagger-spring-boot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/battcn%2Fswagger-spring-boot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/battcn","download_url":"https://codeload.github.com/battcn/swagger-spring-boot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378142,"owners_count":20929296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jdk","springboot","swagger"],"created_at":"2024-09-24T19:53:22.287Z","updated_at":"2025-04-05T18:07:54.575Z","avatar_url":"https://github.com/battcn.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 简介 #\n\n\u003e 什么是 swagger?\n\n**`Swagger` 是一款自动生成在线文档 + 接口调试的工具。在 WEB 开发中不可否认的是我们需要给客户端提供 API 接口，这个时候需要借助 postman、rap 等工具\n进行调试，以便于接口能正常交付给客户端人员，用过其它工具的应该知道一个 POST 请求一堆参数是非常枯燥且烦人的事情，而 swagger 就是让你摆脱这种束缚感....**\n\n\u003e 项目群\n\n**近期询问 `swagger-spring-boot-starter` 的朋友越来越多，所以就创建了一个意见反馈群（`QQ群：868804589`），BUG反馈和优化/美化的建议都可以在群里进行交流**\n\n\u003e 源码地址\n\n- GitHub：[https://github.com/battcn/swagger-spring-boot](https://github.com/battcn/swagger-spring-boot \"https://github.com/battcn/swagger-spring-boot\")\n- 码云：[https://gitee.com/battcn/spring-boot-starter-swagger/](https://gitee.com/battcn/spring-boot-starter-swagger/ \"https://gitee.com/battcn/spring-boot-starter-swagger/\")\n\n`swagger-spring-boot-starter` 是一款建立在`swagger`基础之上的工具包，利用SpringBoot自动装配的特性，简化了传统`swagger`的繁琐配置\n\n\u003e 项目介绍\n\n- **`swagger-vue` ：采用 Vue 编写的源代码，如果您对UI有更好的想法或者建议可以在该项目上进行扩展，它就是 UI 的源文件**\n- **`swagger-vue-ui` ：编译后的纯 HTML 文件，如果你对 `swagger-spring-boot-starter` 包中的 UI 感到不满，你也可以选择排除 `swagger-vue-ui` 然后用第三方的...**\n- **`swagger-spring-boot-starter` ： 自动装配 swagger 的扩展包**\n\n有兴趣扩展自己的Starter包的可以参考文章：[编写自己的starter项目](http://blog.battcn.com/2017/07/13/springboot/springboot-starter-swagger/ \"编写自己的starter项目\")\n\n**如果该项目对您有帮助，欢迎Fork和Star，有疑问可以加 `QQ：1837307557`一起交流 ，如发现项目BUG可以提交`Issue`**\n\n# 使用 #\n\n**1.X 版本需要在启动类添加 `@EnableSwagger2Doc` 但是 2.X 版本后无需添加，请知晓...**\n\n- 在`pom.xml`中引入依赖：\n\n``` xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.battcn\u003c/groupId\u003e\n    \u003cartifactId\u003eswagger-spring-boot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e2.1.5-RELEASE\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\u003e 中文乱码\n\n如果遇到中文乱码，请确保自己的资源文件是 `UTF-8` 然后添加以下配置（一般情况只要自身环境正确，无需额外配置）\n\n``` properties\nserver.tomcat.uri-encoding=UTF-8\nspring.http.encoding.force=true\nspring.http.encoding.enabled=true\nspring.http.encoding.charset=UTF-8\nspring.messages.encoding=UTF-8\n```\n\n\u003e 访问 404 \n\n如果遇到 访问 `swagger-ui.html` 404 的问题，尝试如下方案\n\n``` java\nimport org.springframework.context.annotation.Configuration;\nimport org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;\nimport org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;\n\n/**\n * 解决 swagger-ui.html 访问路径 404 问题\n *\n * @author Levin\n */\n@Configuration\npublic class SwaggerMvnConfiguration extends WebMvcConfigurationSupport {\n\n    @Override\n    protected void addResourceHandlers(ResourceHandlerRegistry registry) {\n        registry.addResourceHandler(\"/**\").addResourceLocations(\"classpath:/META-INF/resources/\").setCachePeriod(0);\n    }\n    \n}\n```\n\n\n\n- 在`application.yml`中添加\n\n``` yaml\nspring:\n  swagger:\n    enabled: true\n```\n\n- 在`application.properties`中添加\n\n``` properties \nspring.swagger.enabled=true\n```\n\n\n# 更新记录 #\n```\n2.1.5\n  发布时间：2019-03-04\n  更新内容：\n    1.修复当前 issues\n    2.新增接口搜索功能\n    3.优化VUE代码\n    4.最近在和公司前端大佬一起讨论代码重构和新版本UI渲染的问题，\n    同时2.1.5页是最稳定版本，届时没有BUG的情况下会重心在新版本研发\n2.1.3\n  发布时间：2018-12-27\n  更新内容：\n    1.修复多层`content-path`时，路径404BUG\n    2.修复嵌套实体时，`@ApiModelProperty` 必填项显示错误\n    3.修复新版UI无缩进问题\n    4.修复接口过多情况下，未出现滚动条BUG\n    5.当接口类型是 `JAVA POJO`时，渲染的对象添加颜色区分\n    6.UI自适应优化，在不同分辨率下显示更加友好\n    7.UI兼容性优化，支持在IE11，EDGE等浏览器显示\n    8.致歉：近期较忙，所以发布周期延后，十分抱歉\n2.1.2\n  发布时间：2018-11-14\n  更新内容：\n    1.解决调试面板 String 类型数据不显示\n    2.解决请求参数为 JSONObject时 没有按 JSON 传输\n    3.调试接口界面中 请求参数值可以添加 @ApiModelProperty 注解中 example 配置的默认值\n2.1.1\n  发布时间：2018-11-08\n  更新内容：\n    1.调试面板JSON渲染美化\n    2.美化登陆页面UI\n    3.修复 TreeNode 数据结构导致内存溢出BUG\n    4.优化VUE的包目录结构和代码风格\n2.1.0\n  发布时间：2018-09-22\n  更新内容：\n    1.调试面板JSON渲染美化\n    2.修复授权模式下任意密码可以登陆问题\n    3.修复ApiModelProperty#required 不生效问题\n2.0.7\n  发布时间：2018-08-17\n  更新内容：\n    1.解决无请求参数无法调试，js报错\n    2.解决编辑 json 会导致 json 加一个双引号传输\n2.0.6\n  发布时间：2018-07-25\n  更新内容：\n    1.解决请求错误时，异常信息不渲染的BUG\n    2.优化登陆保存策略\n2.0.5\n  发布时间：2018-07-24\n  更新内容：\n    1.修复 spring.swagger.host 导致调试面板失效BUG\n2.0.4\n  发布时间：2018-07-23\n  更新内容：\n    1.修改未自动注入BUG（在2.0.3中需要写明 ComponentScan）\n2.0.2（具体效果看 samples-basic 中的项目示例）\n2.0.3\n  发布时间：2018-07-17\n  更新内容：\n    1.UI美化\n    2.路由优化\n    3.文件上传控件美化\n2.0.2（具体效果看 samples-basic 中的项目示例）\n  发布时间：2018年07月10日\n  更新内容：\n    1.UI添加响应结果\n    2.UI添加全局认证窗口\n    3.修复接口过多导致内存溢出泄露BUG\n    4.优化代码风格与标准\n    5.美化弹窗\n    6.添加安全验证过滤器（这样一来即使你想线上使用 swagger 一样可以）\n    7.登陆UI，保障接口安全\n    8.添加请求响应时间\n    9.升级Spring Boot 版本为 2.0.3-RELEASE\n2.0.1\n  发布时间：2018年06月19日\n  更新内容：\n    1.重写UI\n    2.升级Spring Boot 为2.0.2\n    3.支持接口全局认证（设置一次 Token 需验证的地址自动将值写入到请求头/请求体中）\n    4.全局响应返回\n    5.支持可选的 Bean 验证插件；\n        由于日常开发中发现默认启动的验证插件扫描耗时比较久（由于我电脑弱，扫描时间大概在3-5秒...）\n        故而将插件修改为可选的，默认是关闭\n    6.支持选项卡切换\n    7.修复多余的斜杠\n1.4.5\n  发布时间：2018年04月26日\n  更新内容：\n    1.解决配置 `context-path` 导致 `swagger-ui.html` 无法显示BUG\n1.4.4\n  发布时间：2018年01月05日\n  更新内容：\n    1.优化选项卡切换\n1.4.3\n  发布时间：2017年12月22日\n  更新内容：\n    1.修复CRUL口令\n    2.提升操作体验\n1.4.2\n  发布时间：2017年12月15日\n  更新内容：\n    1.修复CRUL口令\n    2.渲染菜单列表颜色\n1.4.1\n  发布时间：2017年12月13日\n  更新内容：\n    1.修复CRUL口令\n    2.修复DELETE类型请求部分存在404问题\n1.4.0\n  发布时间：2017年12月14日\n  更新内容：\n    1.PATCH无法正确渲染\n1.3.9\n  发布时间：2017年9月17日 \n  更新内容：\n    1.修复对象深度拷贝\n1.3.8\n  发布时间：2017年12月8日 \n  更新内容：\n    1. 解决1.1.0发版中的bug    \n1.1.0\n  发布时间：2017年12月1日\n  更新内容：\n    1. 完成基础功能\n```\n\n# 重写UI #\n\n\u003e 操作风格 - 2.0.2 版本\n\n``` java\n# 2.0.3 版本新特性（开启后访问 swagger-ui.html 会自动路由到登陆页面，保障接口信息不被暴露）\nspring.swagger.security.filter-plugin=true\n# 配置账号密码\nspring.swagger.security.username=battcn\nspring.swagger.security.password=battcn\n```\n\n![接口说明](doc/img/2_4.png)\n\n\u003e 操作风格 - 2.0.1 版本\n\n``` java\n# 配置\nspring.swagger.api-key.key-name=myToken\n# 2.0.1 版本新特性 （支持可选的 Bean 验证插件）\nspring.swagger.validator-plugin=false\n# 定义全局响应返回\nspring.swagger.global-response-messages.POST[0].code=400\nspring.swagger.global-response-messages.POST[0].message=server response 400\nspring.swagger.global-response-messages.POST[1].code=404\nspring.swagger.global-response-messages.POST[1].message=server response 404\n```\n\n![接口说明](doc/img/2_1.png)\n\n![接口说明](doc/img/2_2.png)\n\n![接口说明](doc/img/2_3.png)\n\n\n\u003e 操作风格 - 1.4.3支持\n\n![接口说明](doc/img/4.png)\n\n\u003e 接口说明：折叠式Model\n\n![接口说明](doc/img/1.png)\n\n\n\u003e 接口说明：折叠式表单响应内容，告别长长的滚动条\n\n![接口说明](doc/img/2.png)\n\n\u003e 在线调试\n\n![在线调试](doc/img/3.png)\n\n\n## 配置说明 ##\n\n`spring.swagger.enabled`：提供该配置目的是方便多环境关闭，一般生产环境中不会暴露它，这时候就可以通过 `java -jar xx.jar --spring.swagger.enabled=false` 动态关闭，也可以在多环境配置写好\n\n\n### properties ###\n\n```\nspring.swagger.enabled=是否启用swagger，默认：true\nspring.swagger.title=标题\nspring.swagger.description=描述信息\nspring.swagger.version=版本\nspring.swagger.license=许可证\nspring.swagger.licenseUrl=许可证URL\nspring.swagger.termsOfServiceUrl=服务条款URL\nspring.swagger.contact.name=维护人\nspring.swagger.contact.url=维护人URL\nspring.swagger.contact.email=维护人email\nspring.swagger.base-package=swagger扫描的基础包，默认：全扫描\nspring.swagger.base-path=需要处理的基础URL规则，默认：/**\nspring.swagger.exclude-path=需要排除的URL规则，默认：空\nspring.swagger.host=文档的host信息，默认：空\nspring.swagger.globalOperationParameters[0].name=参数名\nspring.swagger.globalOperationParameters[0].description=描述信息\nspring.swagger.globalOperationParameters[0].modelRef=指定参数类型\nspring.swagger.globalOperationParameters[0].parameterType=指定参数存放位置,参考ParamType:(header,query,path,body,form)\nspring.swagger.globalOperationParameters[0].required=指定参数是否必传，默认false\n#下面分组是\nspring.swagger.groups.\u003cname\u003e.basePackage=swagger扫描的路径\n#比如\nspring.swagger.groups.基础信息.basePackage=com.battcn.controller.basic\n\n# 关闭 JSR\nspring.swagger.validator-plugin=false\n# 全局消息体\nspring.swagger.global-response-messages.GET[0].code=400\nspring.swagger.global-response-messages.GET[0].message=server response 400\nspring.swagger.global-response-messages.POST[0].code=400\nspring.swagger.global-response-messages.POST[0].message=server response 400\nspring.swagger.global-response-messages.POST[1].code=404\nspring.swagger.global-response-messages.POST[1].message=server response 404\n```\n\n\n### yaml ###\n\n以下为 `application.yml` 配置示例\n\n``` yaml\nspring:\n  swagger:\n    enabled: true\n    title: 标题\n    description: 描述信息\n    version: 系统版本号\n    contact:\n      name: 维护者信息\n    base-package: swagger扫描的基础包，默认：全扫描(分组情况下此处可不配置)\n    #全局参数,比如Token之类的验证信息可以全局话配置\n    global-operation-parameters:\n    -   description: 'Token信息,必填项'\n        modelRef: 'string'\n        name: 'Authorization'\n        parameter-type: 'header'\n        required: true\n    groups:\n      basic-group:\n        base-package: com.battcn.controller.basic\n      system-group:\n        base-package: com.battcn.controller.system\n```\n\n\n# 贡献者 #\n\nLevin：1837307557@qq.com  \n\n- 个人博文：[http://blog.battcn.com](http://blog.battcn.com \"http://blog.battcn.com\")\n\n_Rock：995269937@qq.com\n\n\n# 常用注解说明 #\n\n* `@Api`:一般用于Controller中,用于接口分组。（**`如：@Api(value = \"用户接口\", description = \"用户接口\", tags = {\"1.1.0\"})`**\n\n* `@ApiOperation`:接口说明,用于api方法上。（**`如： @ApiOperation(value = \"用户查询\", notes = \"根据ID查询用户信息\")`**）\n\n* `@ApiImplicitParam`:参数说明,适用于只有一个请求参数,主要参数\n\n* `@ApiImplicitParams`:多个参数说明,主要参数参考上面`@ApiImplicitParam`\n\n* `@ApiModel`:实体类说明\n\n* `@ApiModelProperty`：实体参数说明\n\n\n# 如何参与 #\n\n有兴趣的可以联系本人（Pull Request），参与进来一起开发，美化UI与配置项一起完善\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbattcn%2Fswagger-spring-boot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbattcn%2Fswagger-spring-boot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbattcn%2Fswagger-spring-boot/lists"}