版权声明:本文为博主原创文章,转载请附上链接。 https://blog.csdn.net/qq_36182135/article/details/81559886
前后端分离的大趋势下,后端除了要开发,最重要的就是编写API文档了。但是,由于开发任务的不断增加,接口增加过多,这给API的编写造成一定的难度,使得文档整合的越来越杂糅。
所以,Swagger 就是用来解决这一问题的工具。开发人员不用再提供文档,只需要给出一个Swagger 地址,就可以让需要调用到接口的人员在线获取数据,测试接口功能,可以说是非常便利了。
-
增加Swagger2 的依赖
版本选择方面,现在maven在线仓库中,Swagger2.7的版本选择下载较多,而且2.7版本已经出来一年了,稳定性会比较高,所以本文选择2.7版本进行配置
<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>
-
配置Swagger2
package pers.hong.demo.config;
import org.springframework.beans.factory.annotation.Autowired;
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;
import java.beans.PersistenceDelegate;
/**
* @Description:
* @Auther: hong
* @Date: 2018/08/20
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket creatApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("pers.hong.demo.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger测试")
.description("生成的接口如下")
.version("1.0")
.build();
}
}
其中,creatApi()方法是通过new一个Docket构造器来进行Api的配置,apiInfo()就是文档的参数配置,apis()就是指定想要生成的API的路径,apiInfo()方法通过ApiInfoBuilder来配置各项属性,包括标题、描述、版本等。
这样子Swagger的基本配置就OK了,打开localhost:8080/swagger-ui.html就可以看到
如果遇到下面这个弹窗,清除浏览器缓存就行了
-
Swagger2 的使用
测试接口类如下
package pers.hong.demo.controller;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import pers.hong.demo.config.Result;
import pers.hong.demo.config.ResultGenerator;
import pers.hong.demo.entity.SysUser;
import pers.hong.demo.service.SysUserService;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Map;
/**
* @Description:
* @Auther: hong
* @Date: 2018/08/16
*/
@RestController
public class SysUserController {
@Autowired
private SysUserService sysUserService;
@RequestMapping("/")
public void index( HttpServletResponse response) throws IOException {
response.sendRedirect("/login.html");
}
@ApiOperation(value = "登录接口测试")
@RequestMapping(value = "/login", method = RequestMethod.POST)
public Result login(@RequestBody @ApiParam(value = "用户实体类") SysUser sysUser) {
Result result = ResultGenerator.genFailResult("登录失败");
if (StringUtils.isEmpty(sysUser.getUserName()) || StringUtils.isEmpty(sysUser.getPassword())) {
result.setMessage("请填写登录信息!");
}
SysUser loginUser = sysUserService.updateTokenAndLogin(sysUser.getUserName(), sysUser.getPassword());
if (loginUser != null) {
result = ResultGenerator.genSuccessResult(loginUser);
}
return result;
}
}
进入Swagger页面,点开login接口
输入value,进行测试,就可以看到返回数据和状态码了
以上就是基本的Swagger使用,还有一些注解和方法我没有使用,不过也不难就是了,总的来说,Swagger是一款极易上手的API文档编写工具