关键词:
本文github位置:https://github.com/WillVi/springboot-swagger2-demo
环境准备
- JDK版本:1.8
- Spring boot版本:1.5.16
- Swagger及其Swagger-ui版本:2.6.1(关于swagger-ui版本 每个版本的汉化方式可能有不同)
- 默认url:http://localhost:8080/swagger-ui.html
Maven依赖
<!-- swagge2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<!-- swaggerui用于展示swagger页面 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
注意事项:
swagger-ui依赖 有可能会与com.google.guava
冲突 提供一个解决办法:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
<!-- 将冲突包移除 -->
<exclusions>
<exclusion>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
</exclusion>
</exclusions>
</dependency>
配置文件
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket api() {
// 统一设置返回描述
List<ResponseMessage> responseMessages = new ArrayList<>();
responseMessages.add(new ResponseMessageBuilder().code(400).message("请求参数有误").build());
responseMessages.add(new ResponseMessageBuilder().code(401).message("未授权").build());
responseMessages.add(new ResponseMessageBuilder().code(403).message("禁止访问").build());
responseMessages.add(new ResponseMessageBuilder().code(404).message("请求路径不存在").build());
responseMessages.add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef("string")).build());
return new Docket(DocumentationType.SWAGGER_2)
// 禁用默认返回描述
.useDefaultResponseMessages(false)
// 启用新的返回描述
.globalResponseMessage(RequestMethod.GET, responseMessages)
.globalResponseMessage(RequestMethod.POST, responseMessages)
.globalResponseMessage(RequestMethod.PATCH, responseMessages)
.globalResponseMessage(RequestMethod.PUT, responseMessages)
.globalResponseMessage(RequestMethod.DELETE, responseMessages)
// 设置基本信息
.apiInfo(apiInfo())
.select()
// 设置哪些api被扫描
.apis(RequestHandlerSelectors.basePackage("cn.willvi.springbootswaggerdemo"))
// 设置路径
.paths(PathSelectors.any())
.build();
}
/**
* 设置基本信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("我的接口文档")
// 描述
.description("这是我的第一个接口文档")
// 版本号
.version("1.0")
// 项目的链接
.termsOfServiceUrl("")
// 作者
.license("willvi")
.licenseUrl("")
.build();
}
}
Swagger注解详解
@Api 设置Controller整体信息
注解位置:Controller类上
/**
* value url路径值(汉化后不起作用) http://xxx/swagger-ui.html#/demo-controller中的 demo-controller即为value
* tags 设置这个值、value的值会被覆盖(汉化后有bug最好不写)
* description 对api资源的描述
* basePath 基本路径可以不配置
* position 如果配置多个Api 想改变显示的顺序位置
* produces 例如, "application/json, application/xml" 页面上的 Response Content Type (响应Content Type)
* consumes 例如, "application/json, application/xml"
* protocols Possible values: http, https, ws, wss.
* authorizations 高级特性认证时配置
* hidden 配置为true 将在文档中隐藏
*/
@Api(value = "Swagger 注解使用",description = "123")
@ApiOperation 设置每个方法(接口)信息
注解位置:方法上
/**
* value 页面tab右侧值
* tags 如果设置这个值、value的值会被覆盖
* description 对api资源的描述
* basePath 基本路径可以不配置
* position 如果配置多个Api 想改变显示的顺序位置
* produces 例如, "application/json, application/xml"
* consumes 例如, "application/json, application/xml"
* protocols Possible values: http, https, ws, wss.
* authorizations 高级特性认证时配置
* hidden 配置为true 将在文档中隐藏
* response 返回的对象
* responseContainer 这些对象是有效的 "List", "Set" or "Map".,其他无效
* httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
* code http的状态码 默认 200
* extensions 扩展属性
*/
@ApiOperation(
value = "post",
notes = "这是一个小demo",
produces = "application/json",
response = Person.class
)
@ApiImplicitParams 与 @ApiImplicitParam 设置传入参数信息
注解位置:方法上
注意事项: name必须与参数名相同,不然多出一个参数框
/**
* @ApiImplicitParam
* 当dataType不是对象时可以使用
*
* paramType:参数放在哪个地方
* name:参数代表的含义
* value:参数名称
* dataType: 参数类型,有String/int,无用
* required : 是否必要
* defaultValue:参数的默认值
*/
@ApiImplicitParams(
@ApiImplicitParam(name = "name",value = "name",paramType ="path", dataType = "String")
)
@ApiResponses 设置返回的一些状态码信息
注解位置:方法上
/**
* code http的状态码
* message 描述
* response 默认响应类 Void
* reference 参考ApiOperation中配置
* responseHeaders 参考 ResponseHeader 属性配置说明
* responseContainer 参考ApiOperation中配置
*/
@ApiResponses({@ApiResponse(code = 500, message = "服务器内部错误", response = String.class)})
@ApiModel
描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候
注解位置:实体类上
@ApiModelProperty
描述一个model的属性。
注解位置:实体类每个属性上面
@ApiModelProperty(value = "姓名",name = "name")
@ApiParam
注解位置:方法参数内
/**
* name 属性名称
* value 属性值
* defaultValue 默认属性值
* allowableValues 可以不配置
* required 是否属性必填
* access 不过多描述
* allowMultiple 默认为false
* hidden 隐藏该属性
* example 举例子
*/
public ResponseEntity<String> placeOrder(
@ApiParam(value = "xxxx", required = true) Person person) {
storeData.add(order);
return ok("");
}
Controler示例
@Api(value = "Swagger 注解使用")
@RestController
@RequestMapping("/")
public class DemoController {
@PostMapping("/postHello")
/**
* value url的路径值
* tags 如果设置这个值、value的值会被覆盖
* description 对api资源的描述
* basePath 基本路径可以不配置
* position 如果配置多个Api 想改变显示的顺序位置
* produces 例如, "application/json, application/xml"
* consumes 例如, "application/json, application/xml"
* protocols Possible values: http, https, ws, wss.
* authorizations 高级特性认证时配置
* hidden 配置为true 将在文档中隐藏
* response 返回的对象
* responseContainer 这些对象是有效的 "List", "Set" or "Map".,其他无效
* httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
* code http的状态码 默认 200
* extensions 扩展属性
*/
@ApiOperation(
value = "post",
notes = "这是一个小demo",
produces = "application/json",
response = Person.class
)
/**
* code http的状态码
* message 描述
* response 默认响应类 Void
* reference 参考ApiOperation中配置
* responseHeaders 参考 ResponseHeader 属性配置说明
* responseContainer 参考ApiOperation中配置
*/
@ApiResponses({@ApiResponse(code = 500, message = "服务器内部错误", response = String.class)})
public ResponseEntity<Person> postHello(@RequestBody Person person){
return ResponseEntity.ok(person);
}
@GetMapping("/hello/{name}")
@ApiOperation(
value = "hello world",
notes = "这是一个小demo"
)
/**
* @ApiImplicitParam
* 当dataType不是对象时可以使用
* paramType:参数放在哪个地方
* name:参数代表的含义
* value:参数名称
* dataType: 参数类型,有String/int,无用
* required : 是否必要
* defaultValue:参数的默认值
*/
@ApiImplicitParams(
@ApiImplicitParam(value = "name",paramType ="path", dataType = "String",defaultValue = "world")
)
public String hello(@PathVariable String name){
return "hello " + name;
}
}
Model示例
// 描述一个Model的信息
@ApiModel
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class Person {
@ApiModelProperty(value = "姓名",name = "name")
String name;
int age;
}
swagger汉化
在resources资源下创建
META-INF/resources
文件夹并创建名为swagger-ui.html
文件复制以下内容:
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Swagger UI</title> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/> <link href=‘webjars/springfox-swagger-ui/css/typography.css‘ media=‘screen‘ rel=‘stylesheet‘ type=‘text/css‘/> <link href=‘webjars/springfox-swagger-ui/css/reset.css‘ media=‘screen‘ rel=‘stylesheet‘ type=‘text/css‘/> <link href=‘webjars/springfox-swagger-ui/css/screen.css‘ media=‘screen‘ rel=‘stylesheet‘ type=‘text/css‘/> <link href=‘webjars/springfox-swagger-ui/css/reset.css‘ media=‘print‘ rel=‘stylesheet‘ type=‘text/css‘/> <link href=‘webjars/springfox-swagger-ui/css/print.css‘ media=‘print‘ rel=‘stylesheet‘ type=‘text/css‘/> <script src=‘webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jquery.slideto.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/lodash.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/backbone-min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/swagger-ui.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jsoneditor.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/marked.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/swagger-oauth.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/springfox.js‘ type=‘text/javascript‘></script> <!-- 汉化 --> <script src=‘webjars/springfox-swagger-ui/lang/translator.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lang/zh-cn.js‘ type=‘text/javascript‘></script> </head> <body class="swagger-section"> <div id=‘header‘> <div class="swagger-ui-wrap"> <a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30" src="webjars/springfox-swagger-ui/images/logo_small.png" /><span class="logo__title">swagger</span></a> <form id=‘api_selector‘> <div class=‘input‘> <select id="select_baseUrl" name="select_baseUrl"/> </div> <div class=‘input‘><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div> <div id=‘auth_container‘></div> <div class=‘input‘><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div> </form> </div> </div> <div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div> <div id="swagger-ui-container" class="swagger-ui-wrap"></div> </body> </html>
访问即可
springboot学习——springboot快速整合swagger文档
@[toc]简介优点后端根据swagger语法,自动生成漂亮规范的接口文档。做交互测试。劣势侵入式的,影响程序运行,尤其是传参的时候。注意swagger分1.2版本和2.0版本,差异较大。swagger1.2即swagger-ui;swagger2.0即springfox-swagger。本文介... 查看详情
springboot整合swagger
Swagger使用Swagger有什么用?swagger是一个流行的API开发框架,这个框架以“开放API声明”(OpenAPISpecification,OAS)为基础, 对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计、编码和测试,... 查看详情
springboot整合swagger-ui快速生成在线api文档
目录SpringBoot整合Swagger-ui实现在线API文档本篇要点一、restful风格简单介绍二、SpringBoot与Swagger-ui快速整合1、第一种方式:使用官方依赖2、第二种方式:使用第三方依赖三、swagger-ui的基本注解源码下载参考阅读SpringBoot整合Swagger-u... 查看详情
swaggerlearing-springboot整合swagger
学习了一下swagger。这是编写的Demo源码https://github.com/AmberBar/Learning/tree/master/swagger-learning/swagger需要的小伙伴可以clone直接运行访问地址http://localhost:9999/swagger-ui.html#/ 查看详情
在springboot中整合jersey和springfox-swagger2
前言为了实现RESTfulWebservice和接口说明,基于springboot平台,使用jersey作为JAX-RS的实现,采用swagger文档在线生成工具。提要在实现了springboot集成jersey的swagger文档功能,同时满足SpringMVC整合swagger提供RESTful文档功能。Springboot 集... 查看详情
swagger和springboot整合
Swagger号称全世界最流行的api框架;RestFulApi文档在线自动生成工具=>Api文档与API定义同步更新配置<!--https://mvnrepository.com/artifact/io.springfox/springfox-swagger2--><dependency> <groupId>io.springfox</g 查看详情
springboot和swagger整合
本文来源:https://blog.csdn.net/saytime/article/details/74937664一、依赖<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version& 查看详情
springboot整合swagger-ui
SpringBoot整合Swagger-ui引入依赖<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency>< 查看详情
springboot整合swagger2
一关于SwaggerSwagger能成为最受欢迎的RESTAPIs文档生成工具之一,有以下几个原因:Swagger可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。Swagger可以生成客户端SDK代码用于各种不同的平台上的实现。Swagger... 查看详情
springboot整合swagger
...Api到Postman测试,耗费了不少时间。这次新项目决定使用SpringBoot来做,各方面都节省了不少配置,一想到Api的对接就有点头大,于是决定把Swagger集成进来,实现Api文档的自动生成(通过http://localhost:8080/swagge 查看详情
springboot整合swagger2
手写Api文档的几个痛点:文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。接口返回结果不明确不能直接在线测试接口,通常需要使用工具,比如postman接口文档太多,不好管理 Swagger也就是... 查看详情
springboot整合swagger测试api构建
@Author:SimpleWu什么是Swagger?Swagger是什么:THEWORLD’SMOSTPOPULARAPITOOLING根据官网的介绍:SwaggerInspector:测试API和生成OpenAPI的开发工具。SwaggerInspector的建立是为了解决开发者的三个主要目标。执行简单的API测试生成OpenAPI文档探索新... 查看详情
springboot整合swagger2搭建api在线文档
...阅和测试功能。利用Swagger2很容易构建RESTful风格的API,在SpringBoot中集成Swagger2,步骤如下。1.引入依赖<!--Swagger2--><dependency><groupId> 查看详情
springboot整合swagger框架
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码,允许API来始终保... 查看详情
springboot2整合swagger2-plus
目录一.整合swagger21.加依赖2.写配置3.常用注解:4.演示demo5.实际效果查询新增登录二.整合swagger2-plus1.加依赖2.写配置3.实际应用4.最终效果新增登录一.整合swagger21.加依赖<!--引入swagger2--><dependency><groupId>io.springfox</gr... 查看详情
springboot整合swagger常见问题一
项目启动完,访问swagger-ui页面访问不到,这里可以给他指定一下,创建一个实体类即可@SuppressWarnings("deprecation")@Configurationpublic class WebMVCConfig extends WebMvcConfigurerAdapter { &nb 查看详情
springboot整合swagger2框架
一:什么是SwaggerSwagger是一款通过我们添加的注解来对方法进行说明,来自动生成项目的在线api接口文档的web服务。二:添加Swagger2依赖<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><ve 查看详情
springboot整合swagger2
SpringBoot整合Swagger2相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档。手写Api文档的几个痛点:文档需... 查看详情