springboot研究:springboot使用swagger自动构建api
对于开发人员来说,维护接口文档是一件头疼的事情,因为接口会时不时发生变化。这样可能测试人员或者新入职的同事会看到接口文档跟实际接口有出入。而对于开发人员,接口的变化可能不能很快同步到文档中。swagger可以方便的帮我们维护接口文档。swagger的使用非常简单,下面看一下在springboot中的配置。本文中springboot采用2.1.6版本,swagger采用2.8.0
1.引入swagger依赖
<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>
2.写一个swagger的配置类,如下
@EnableSwagger2
@Configuration
@Profile(value = {"dev"})
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//需要生成api接口的目录,一般是存放controller的目录
.apis(RequestHandlerSelectors.basePackage("boot.web"))
.paths(PathSelectors.any())
.build();
}
/**
* 定义ApiInfo生成函数
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("SpringBoot使用Swagger2维护api文档")
//联系人信息
.contact(new Contact("jinjunzhu", "https://blog.csdn.net/zjj2006", "zjj2006forever@163.com"))
.version("1.0")
.description("API 描述")
.build();
}
}
3.对controller中的的方法和实体类进行配置,这儿的示例是一个UserController中的方法,代码如下:
@Api(value = "用户操作")
@Controller
@RequestMapping("/user")
public class UserController {
@Resource
private UserService userService;
@ApiOperation(value = "根据用户名获取用户", notes="用户名必填")
@ApiImplicitParam(name = "username", required = true)
@RequestMapping(value = "/{username}", method = {RequestMethod.GET})
@ResponseBody
public String getUser(@PathVariable String username) {
return userService.getUser(username).getPassword();
}
@ApiOperation(value = "保存用户", notes="post请求中请求参数是一个json,包括用户名密码,例如:{"username":"zhangsan","password":"123456"}")
@ApiImplicitParam(name = "user", required = true)
@RequestMapping(value = "/saveUser", method = {RequestMethod.POST})
@ResponseBody
public String saveUser(@RequestBody User user) {
try {
userService.insert(user);
return "success!";
} catch (Exception e) {
return "failure!";
}
}
}
@ApiModel("用户实体类")
public class User implements Serializable{
private static final long serialVersionUID = 1L;
private Long id;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
@ApiOperation是一个接口说明 @ApiImplicitParam代表一个单一的参数
配置好后,启动工程,在浏览器输入:
http://localhost:8080/swagger-ui.html#/,返回页面如下:
下面我们重点看saveUser方法,
点击页面上的“Try it out”,输入参数,点击“Execute”,用户信息保存成功。
4.在生产环境中,我们必须禁用swagger,以避免不必要的麻烦。有2种方法可以做到禁用swagger,推荐第一种
1)在SwaggerConfig中增加注解@Profile(value = {"dev"}),同时在application.properties文件中增加:
开发环境spring.profiles.active=dev 生产环境spring.profiles.active=pro 测试环境spring.profiles.active=test
这样就只有开发环境可以使用swagger
2)在SwaggerConfig中增加注解@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true"),同时在application.properties文件中增加:
开发环境swagger.enable=true 生产环境swagger.enable=false 测试环境swagger.enable=false
这样就只有开发环境可以使用swagger
源码地址:https://github.com/jinjunzhu/spring-boot-mybatis
- .NET Core跨平台的奥秘[下篇]:全新的布局
- Equation Group泄露文件分析
- ModelBinder——ASP.NET MVC Model绑定的核心
- 一句代码实现批量数据绑定[下篇]
- 三种属性操作性能比较:PropertyInfo + Expression Tree + Delegate.CreateDelegate
- 解密Myspace密码的姿势
- weblogic安全配置二三事
- 开发自己的Data Access Application Block[下篇]
- 【CSS】格仔背景
- 这年头真的还有USB设备是安全的吗?
- js的动态加载、缓存、更新以及复用(一)使用范围:遇到的问题:目标:页面结构:正文
- js的动态加载、缓存、更新以及复用(二)恼人的命名冲突
- 以【猫叫、老鼠跑、主人醒】为例子,使用 javascript 来实现 观察者模式 (有在线演示)
- Debian/Ubuntu-shell脚本来管理iptables安全策略
- java教程
- Java快速入门
- Java 开发环境配置
- Java基本语法
- Java 对象和类
- Java 基本数据类型
- Java 变量类型
- Java 修饰符
- Java 运算符
- Java 循环结构
- Java 分支结构
- Java Number类
- Java Character类
- Java String类
- Java StringBuffer和StringBuilder类
- Java 数组
- Java 日期时间
- Java 正则表达式
- Java 方法
- Java 流(Stream)、文件(File)和IO
- Java 异常处理
- Java 继承
- Java 重写(Override)与重载(Overload)
- Java 多态
- Java 抽象类
- Java 封装
- Java 接口
- Java 包(package)
- Java 数据结构
- Java 集合框架
- Java 泛型
- Java 序列化
- Java 网络编程
- Java 发送邮件
- Java 多线程编程
- Java Applet基础
- Java 文档注释