SpringBoot 2.0 学习(十一)集成Swagger在线调试
Swagger是什么?
Swagger是一款Restful接口的API文档在线生成+功能测试软件,它是一个规范且完整的框架,用于生成,描述,调用和可视化的restful风格的web服务。前端和后端唯一联系,变成了API接口;API文档自然就成前后端开发人员联系的纽带,变得尤为的重要,swagger就是一款让你更好的书写API文档的框架。
具体操作
第一步:添加依赖
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
<!--lombok依赖 -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.4</version>
<scope>provided</scope>
</dependency>
第二步:配置文件
配置spring.swagger.enabled开启swagger的使用,如果在生产环境中不想用可以在对应的profile下面将它设置为spring.swagger.enabled=false,这样一来接口就不存在暴露的风险
# 扫描的包路径,默认扫描所有
spring.swagger.base-package=com.winterchen
# 默认为 true
spring.swagger.enabled=true
第三步:实体类
注解解释:
-
@Data 自动生成set/get方法
-
@AllArgsConstructor 自动生成所有有参的构造方法
-
@NoArgsConstructor 自动生成无参的构造方法
第四步:restful风格接口@RestController @RequestMapping("/users") @Api(tags = {"用户管理"}, value = "用户管理") public class UserController { private static final Logger log = LoggerFactory.getLogger(UserController.class); @GetMapping @ApiOperation(value = "条件查询(DONE)") @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "用户名", dataType = "String", paramType = "query"), @ApiImplicitParam(name = "password", value = "密码", dataType = "String", paramType = "query"), }) public User query(String username, String password) { log.info("多个参数用 @ApiImplicitParams"); return new User(1L, username, password); } @GetMapping("/{id}") @ApiOperation(value = "主键查询(DONE)") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long", paramType = "path"), }) public User get(@PathVariable Long id) { log.info("单个参数用 @ApiImplicitParam"); return new User(id, "u1", "p1"); } @DeleteMapping("/{id}") @ApiOperation(value = "删除用户(DONE)") @ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long", paramType = "path") public void delete(@PathVariable Long id) { log.info("单个参数用 ApiImplicitParam"); } @PostMapping @ApiOperation(value = "添加用户(DONE)") public User post(@RequestBody User user) { log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam"); return user; } @PutMapping("/{id}") @ApiOperation(value = "修改用户(DONE)") public void put(@PathVariable Long id, @RequestBody User user) { log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 "); } }
第五步:启动类
第六步:效果展示
需要打开浏览器输入http://localhost:8080/swagger-ui.html,更多操作请自行体验…
Swagger2注解解释
-
@Api:用在请求的类上,表示对类的说明
tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置"
-
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value="说明方法的用途、作用" notes="方法的备注说明"
-
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
-
@ApiImplicitParam:在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名 value:参数的汉字说明、解释 required:参数是否必须传 paramType:参数放在哪个地方 · header --> 请求参数的获取:@RequestHeader · query --> 请求参数的获取:@RequestParam · path(用于restful接口)--> 请求参数的获取:@PathVariable · body(不常用) · form(不常用) dataType:参数类型,默认String,其它值dataType="Integer" defaultValue:参数的默认值
-
@ApiResponses:用在请求的方法上,表示一组响应
-
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400 message:信息,例如"请求参数没填好" response:抛出异常的类
-
@ApiModelProperty:用在属性上,描述响应类的属性
-
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
文章参考
https://blog.csdn.net/jiangyu1013/article/details/83107255
https://blog.csdn.net/Winter_chen001/article/details/80748253#commentBox