SpringBoot集成Swagger2
- 首先,什么是
Swagger
?
Swagger
是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful
风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码,允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。
1.新建一个springboot
工程,做一个小demo
,先只勾选web
模块
2.新建controller
包,新建TestController.java
package com.cmj.controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class TestController {
@RequestMapping("test")
public String hello(){
return "==test==";
}
}
3.导入swagger
依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
4.创建swagger
的java
配置类,新建config
包,新建SwaggerConfig.java
增加两个注解
@Configuration注解
,表明它是一个配置类
@EnableSwagger2
注解开启swagger2
package com.cmj.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
- 重启项目,访问
http://localhost:8080/swagger-ui.html
- 页面如下图
- 那为什么是这个页面呢?如下图
5.swaager
配置类的修改
package com.cmj.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 指定controller存放的目录路径
.apis(RequestHandlerSelectors.basePackage("com.cmj.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 文档标题
.title("这是标题")
// 文档描述
.description("这是描述信息")
.termsOfServiceUrl("https://www.baidu.com")
.version("v1")
.build();
}
}
- 重启项目,效果如下
- 可以发现指定了包的路径后,只显示了test-controller这一个
6.对于常用的几个Swagger的注解的意思,可以自行百度查询
7.接下来测试一个post
请求,先新建一个实体类user
package com.cmj.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel
public class user {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
8.新建一个方法
@ApiOperation("登录接口")
@PostMapping("login")
public user login(@RequestBody @ApiParam("用户") user user1){
return user1;
}
9.重启项目,进入页面
/test
有多个是因为没有指定具体的请求方式,用的是@RequestMapping("test")
点开这个/login
,点击右上角的try it out
测试
完善参数,点击execute
这样,基本的集成就完成了