一. 背景介绍
OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程.
现在很多互联网的项目都是使用前后端分离开发模式,所以对于后端开发人员来说,需要找到一个方式实现接口的快速测试和api文档交付.
二. 目标需求
使用springboot 集成 Swagger,生成Swagger接口,实现后端接口开发后的快速测试和与前端开发实现api文档的快速交接,
三. Swagger概述
Swagger是全球最大的OpenAPI规范(OAS)API开发工具框架,支持从设计和文档到测试和部署的整个API生命周期的开发。 (https://swagger.io/)
Spring Boot 可以集成Swagger,生成Swagger接口,Spring Boot是Java领域的神器,它是Spring项目下快速构建项目的框架。
Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口,常用Swagger注解如下:
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述 @ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
四. 代码实现
- 添加坐标
<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>
2.新建swagger的config类Swagger2Configuration.java
//swagger api起始页 http://localhost:31001/swagger-ui.html
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.chen"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("综合练习api文档")
.description("综合练习api文档")
// .termsOfServiceUrl("/")
.version("1.0")
.build();
}
}
3.新建一个api接口,使用swagger的标签对接口进行注解说明
@Api(value="cms页面管理接口",description = "cms页面管理接口,提供页面的增、删、改、查")
public interface CmsPageControllerApi {
//查询全部
@ApiOperation("查询全部")
public QueryResponseResult findAll();
//页面查询
@ApiOperation("分页查询页面列表")
@ApiImplicitParams({@ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="int"),@ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="int")
})
public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest);
}
4.创建controller类实现上面api接口
@RestController
@RequestMapping("/cms/page")
public class PageController implements CmsPageControllerApi {
@Autowired
CmsPageService pageService;
@Override
@GetMapping("/findAll")
public QueryResponseResult findAll() {
return pageService.findAll();
}
@Override
@GetMapping("/list/{page}/{size}")
public QueryResponseResult findList(@PathVariable("page") int page, @PathVariable("size")int size, QueryPageRequest queryPageRequest) {
//调用service
return pageService.findList(page,size,queryPageRequest);
}
}
- 如果我们使用了spring的自动封装参数功能,将参数封装成bean,如果我们想在api中对参数字段注解,可以在这个bean类的参数上使用@ApiModelProperty注解说明
public class QueryPageRequest {
//接收页面查询的查询条件
//站点id
@ApiModelProperty("站点id")
private String siteId;
//页面ID
@ApiModelProperty("页面ID")
private String pageId;
//页面名称
@ApiModelProperty("页面名称")
private String pageName;
//别名
@ApiModelProperty("别名")
private String pageAliase;
//模版id
@ApiModelProperty("模版id")
private String templateId;
}
6.最后,启动项目,输入 项目地址/swagger-ui.html打开swagger生成的api文档页面,输入参数,点击后面的 Try it out! 按钮就可以看到接口调用结果