基于上一章集成mybatis:(使用了里面的controller)
https://blog.csdn.net/qq_22860341/article/details/81097059
swagger
它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api。
Swagger概述
Swagger是一组围绕OpenAPI规范构建的开源工具,可帮助设计、构建、记录和使用REST API。简单说下,它的出现就是为了方便进行测试后台的restful形式的接口,实现动态的更新,当我们在后台的接口修改了后,swagger可以实现自动的更新,而不需要认为的维护这个接口进行测试。
Swagger常用注解
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiParamImplicitL:一个请求参数
@ApiParamsImplicit 多个请求参数
集成Swagger
加入依赖:
截止2018.7.19最新版本。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
添加SwaggerConfiguration配置
与启动类同级包建立Swagger2
Swagger2.java
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2 {
//swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build();
}
//构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Spring Boot 测试使用 Swagger2 构建RESTful API")
//创建人
.contact(new Contact("cookie", "http://www.baidu.com", "2118119173@qq.com"))
//版本号
.version("1.0")
//描述
.description("用户管理")
.build();
}
}
通过@Configuration注解,表明它是一个配置类,@EnableSwagger2开启swagger2。
apiINfo()配置一些基本的信息。apis()指定扫描的包会生成文档。再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。
select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。
Controller文档内容
一下以用户为例:
import com.example.demo.model.User;
import com.example.demo.service.UserService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@Api(value = "usercontroller",description = "用户管理")
@RestController
public class UserController {
@Autowired
private UserService userService;
/**
* 获取用户列表
* @return list
*/
@ApiOperation(value ="查询所有用户",notes ="",httpMethod = "GET")
@GetMapping("/user")
public List<User> userList(){
return userService.selectAllUser();
}
/**
* 查询用户根据id
* @return USer对象
* @param id
*/
@ApiOperation(value = "查询用户",notes = "根据用户id查询用户",httpMethod = "GET")
@ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
@GetMapping("/user/{id}")
public User getUserById(@PathVariable String id){
User user = userService.selectByPrimaryKey(id);
return user;
}
/**
* 新增User
* @param user
* @return success or error
*/
@ApiOperation(value = "新增用户",notes = "",httpMethod = "POST")
@ApiImplicitParam(name = "user",value = "用户实体",required = true,dataType = "User")
@PostMapping("/user")
public String createUser(@RequestBody User user){
int num = userService.insert(user);
if(num>0){
return "success";
}
return "error";
}
/**
* 更新User
* @param user
* @return success or error
*/
@ApiOperation(value = "更新用户",notes = "根据用户id更新用户",httpMethod = "PUT")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String"),
@ApiImplicitParam(name = "user",value = "用户实体,传入更改后的数据",required = true,dataType = "User")
})
@PutMapping("user/{id}")
public String updateUser(@PathVariable String id,@RequestBody User user){
int num = userService.updateByPrimaryKey(user);
if(num>0){
return "success";
}
return "error";
}
/**
* 删除用户
* @param id
* @return success or error
*/
@ApiOperation(value = "删除用户",notes = "",httpMethod = "DELETE")
@ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
@DeleteMapping("user/{id}")
public String deleteUser(@PathVariable String id){
int num = userService.deleteByPrimaryKey(id);
if(num>0){
return "success";
}
return "error";
}
}
最后启动项目:访问 http://localhost:8080/swagger-ui.html