- 1.Swagger项目
- 2.Swagger
- 2.1 swagger 概念
- 2.2 swagger 常用注解
项目部分代码，只展示与Swagger相关
1）在pom.xml文件中添加swagger
io.springfox
springfox-swagger2
2.6.1
io.springfox
springfox-swagger-ui
2.6.1
com.github.xiaoymin
knife4j-spring-boot-starter
2.0.9
2）配置swagger
package com.example.sdv.config;
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;
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(documentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.sdv.controller")) //添加controller的映射路径
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("实现从数据库里面拿取数据")
.termsOfServiceUrl("www.baidu.com")
.version("1.0")
.build();
}
}
3）在controller中使用swagger
package com.example.sdv.controller;
import com.example.sdv.entity.UserDO;
import com.example.sdv.service.UserDoService;
import io.swagger.annotations.Api;
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.*;
@RestController
public class UserController {
@Autowired
UserDoService userDoService;
@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
@RequestMapping(value = "user/{id}", method = RequestMethod.GET)
public UserDO getUserById(@PathVariable(value = "id") Integer id) {
return userDoService.getUserInfo(id);
}
@ApiOperation(value = "获取用户列表", notes = "获取用户列表")
@RequestMapping(value = "users", method = RequestMethod.GET)
public List getUserList() {
return userDoService.selectAll();
}
@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "UserDO")
@RequestMapping(value = "user", method = RequestMethod.POST)
public int add(@RequestBody UserDO user) {
return userDoService.save(user);
}
@ApiOperation(value = "删除用户", notes = "根据url的id来指定删除用户")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
@RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
public String delete(@PathVariable(value = "id") Integer id) {
int result = userDoService.deleteById(id);
if (result >= 1) {
return "删除成功！";
} else {
return "删除失败！！";
}
}
}
4）启动类（配置允许Swagger2）
package com.example.sdv;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.scheduling.annotation.EnableScheduling;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableSwagger2
@SpringBootApplication
@ComponentScan(basePackages = "com.example.sdv.*")
@MapperScan(basePackages = "com.example.sdv.dao.*")
@EnableCaching
@EnableScheduling
public class SdvApplication {
public static void main(String[] args) {
SpringApplication.run(SdvApplication.class, args);
}
}
5）跑起来的效果
swagger是一个简单的Restful API文档生成管理工具，根据我们自己的配置信息能够自动生成、描述、调用和可视化restful风格并且实时更新的web服务，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。官方地址
2.2 swagger 常用注解a) @Api：用于类上，说明该类的作用
@Api(tags = "测试")
public class UserController {} //说明该类的作用是用于测试
b）@ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义
@ApiOperation(
value = "Find purchase order by ID",
notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
response = Order,
tags = {"Pet Store"})
c) @ApiParam请求属性
public ResponseEntitycreateUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user)
d) @ApiResponse：响应配置
@ApiResponse(code = 400, message = "Invalid user supplied")
e) @ApiResponses ：响应集配置
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
f) @ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path"),
@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "UserDO")
})
g) @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
h) @ApiModel ：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；
@Data
@ApiModel // 在实体类上边使用，标记类时swagger的解析类
public class UserDTO{
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("年龄")
private Integer age;
}
i) @ApiModelProperty：描述一个model的属性
@ApiModelProperty(value = "id",example = "111")
private int id=111; //在swagger界面上 id的example值为111
f) @ResponseHeader ： 响应头设置
@ResponseHeader(name="head1",description="response head conf")
