一、为什么要用 Swagger
现在的开发模式,一般都是前后端分离的,开发接口文档就显得尤为重要,前端人员需要按照后端的功能文档调用对应的接口。在没有使用 API 文档之前,很多公司都是在纸或者 MarkDown 上写文档,不仅效率低,在进行前后端交互的时候也很容易出问题。
Swagger 是一款 API 构建工具,用于满足开发人员构建 API 的需求。Swagger 使用交互式的 API 文档来改善开发人员的体验,并提供无开销的测试功能,还支持可视化的 UI 文档界面。通过 UI 文档界面,前端人员可以很清楚的知道每个接口对应的功能,后端开发人员也可以进行相应的代码测试。
二、Spring Boot 整合 Swagger
在 SpringBoot 中整合 Swagger 很简单,只需要添加对应的依赖、然后配置相关的 Bean 即可,然后使用合适的注解用于文档说明,下面我们就来这么做。
在 pom.xml 中引入对应的依赖
<!-- 引入 swagger 对应的依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
Swagger 配置类 SwaggerConfiguration
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.jas"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger构建api文档")
.description("swaggerTest")
.version("1.0")
.build();
}
}
测试的 Controller
@ResponseBody
@GetMapping("/test")
@ApiOperation(value = "swagger 测试", httpMethod = "GET", response = String.class)
public String testSwagger(String userName) {
return "Hello " + userName;
}
三、访问 UI 页面文档
输入 http://{ip地址}:{端口号}/{资源路径,如果有配置}/swagger-ui.html 即可访问到 Swagger 文档页面,如下
后端开发人员可以在 API 文档上进行测试,方便问题的排查,前端人员也可以很清晰的知道每个接口对应的功能,然后就可以放心的开发啦。
四、常用的文档注解与属性
@ApiProperty:用对象接收参数时,说明属性信息
@ApiParam:描述某个参数
@Api:用于标注在 Controller 上
- description:Controller 描述信息
@ApiOperation :对 Controller 中的资源进行定义
-
value:说明信息
-
httpMethod:HTTP 请求的方式
-
response:返回值类型
如果请求被拦截需要添加请求不拦截
,"/swagger-ui.html"
,"/swagger-resources/**"
配置为@RequestBody
@RequestMapping(value="", method=RequestMethod.POST)
public String post(@RequestBody Book book) {
books.put(book.getId(), book);
return "success";
}
在实体类中添加注解
public class Book {
@ApiModelProperty("名字")
private String name;
@ApiModelProperty("价格")
private String price;
@ApiModelProperty("关联id")
private Long id;