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
- 基于OpenCV的跳一跳外挂实现原理
- React Native 0.50版本新功能简介
- Android滤镜效果实现及原理分析
- Spring Boot入门及整合mybatis
- Swift开发React Native组件
- 深入理解Android插件化技术
- Kotlin DSL详解
- 大规模异常滥用检测:基于局部敏感哈希算法——来自Uber Engineering的实践
- 事务与一致性:刚性or柔性?
- 文本相似度算法小结
- return的值都去哪了?去哪了,“谁伸手了,return的结果就给谁”
- 面试时对方问你,“xxx需求你是怎么做的”?你可以这样回答
- vue.js的条件渲染,其实就是模板里面写if else
- vue.js的插槽 - slot 是啥?要我说,它就是个“形参”
- 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 文档注释
- 爬虫工程师也应该会的 NodeJS 知识(三)- 快速抛弃 execjs
- 八皇后问题Python实现
- 进击吧!Pythonista(6/100)
- 进击吧!Pythonista(9/100)
- 数据结构基础(一)数组,矩阵
- pytest 测试框架学习(3):pytest.approx
- pytest 测试框架学习(4):pytest.fail
- SpringBoot 开发秘籍 - 启动时配置校验
- pytest 测试框架学习(5):pytest.skip
- pytest 测试框架学习(6):pytest.importorskip
- Java 自定义注解及使用场景
- pytest 测试框架学习(8):pytest.exit
- Linux傻瓜式四步完美安装Python3.7
- 【译】10 个最有用的 git log 技巧
- Hibernate的入门(Hibernate的环境搭建、Hibernate的API)