pontuss 2020-04-11
一.描述
Swagger是一个规范的,标准的框架。用于生成、描述、调用和可视化Restful风格的Web服务。
二.使用
1.引入pom依赖:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
2.创建Swagger的配置类:
package com.apps.swagger; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.schema.ModelRef; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList; import java.util.List; @Configuration @EnableSwagger2 public class Swagger2 extends WebMvcConfigurationSupport { @Bean public Docket createRestApi() { ParameterBuilder tokenPar = new ParameterBuilder(); List<Parameter> pars = new ArrayList<Parameter>(); tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build(); pars.add(tokenPar.build()); return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.apps.controller")) .paths(PathSelectors.any()) .build() .globalOperationParameters(pars) .apiInfo(apiInfo()); } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**").addResourceLocations("classpath:/META-INF/resources/").setCachePeriod(0); //registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/").setCachePeriod(0); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Sawgger2 API文档") // .description(",http://www.baidu.com") // .termsOfServiceUrl("http://www.baidu.com") .version("1.0") .build(); } private class Invalid{ } }
三.Swagger的注解即其说明:
@ApiOperation:用在方法上,用于给方法增加说明
@Api:用在类上,说明该类的主要作用
@ApiModel: 用在实体类上,描述一个对象的信息
@ApiModelProperety: 用在实体类的属性中,描述一个model的属性
@ApiImplicitParams: 用在方法上,包含一组参数说明
@ApiImplicitParam: 给方法如参数增加说明
@ApiResponses:用于表示一组响应。
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
? l code:数字,例如400
? l message:信息,例如"请求参数没填好"
? l response:抛出异常的类
/** * @program: jpademo * @description: EmployeeController * @create 2018-10-23 11:07 */ ? @RestController @RequestMapping("emp") @Api(value = "用户管理类") public class EmployeeController { ? @Autowired private EmployeeReposiroty employeeReposiroty; ? /** * 增加人物 * @param employee * @return */ @PostMapping(value = "employee") @ApiOperation(value = "新增一个用户",notes = "新增之后返回对象") @ApiImplicitParam(paramType = "query",name = "employee",value = "用户",required = true) @ApiResponse(code = 400,message = "参数没有填好",response = String.class) public String insert(Employee employee){ Employee employee1 = employeeReposiroty.save(employee); if(employee1 != null) { return SysNode.Judge.SUCCESS.getResult(); }else { return SysNode.Judge.FAILD.getResult(); } } ? /** * 删除单个用户 * @param id * @return */ @DeleteMapping(value = "employee/{id}") @ApiOperation(value = "删除用户",notes = "根据成员id删除单个用户") @ApiImplicitParam(paramType = "path",name = "id",value = "用户id",required = true,dataType = "Integer") @ApiResponse(code = 400,message = "参数没有填好",response = String.class) public String delete(@PathVariable("id")Integer id){ try{ employeeReposiroty.deleteById(id); return SysNode.Judge.SUCCESS.getResult(); }catch (Exception e){ e.printStackTrace(); return SysNode.Judge.FAILD.getResult(); } } ? /** * 修改单个成员 * @param employee * @return */ @PutMapping(value = "employee/{id}") @ApiOperation(value = "修改用户信息",notes = "根据成员id修改单个用户") public String update(Employee employee){ /** * save方法如果参数属性缺失,会导致原本存在的数据为null */ Employee employee1 = employeeReposiroty.saveAndFlush(employee); if (employee1 != null) { return SysNode.Judge.SUCCESS.getResult(); }else { return SysNode.Judge.FAILD.getResult(); } } ? /** * 获取所有成员,升序排列 * @return */ @GetMapping(value = "employee/sort") @ApiOperation(value = "查询全部用户",notes = "默认根据升序查询全部用户信息") public List<Employee> findAll(){ Sort orders = new Sort(Sort.Direction.DESC,"employeeId"); List<Employee> employeeList = employeeReposiroty.findAll(orders); return employeeList; } ? /** * 获取所有成员,升序排列 * @return */ @GetMapping(value = "employee/pageSort") @ApiOperation(value = "查询用户信息",notes = "查询用户信息") @ApiImplicitParams({ @ApiImplicitParam(paramType = "query",name = "sort",value = "排序方式:asc|desc",dataType = "String",required = true), @ApiImplicitParam(paramType = "query",name = "pagenumber",value = "第几页",dataType = "Integer",required = true), @ApiImplicitParam(paramType = "query",name = "pageSize",value = "分页数",dataType = "Integer",required = true) }) public List<Employee> findAllByPage(String sort,Integer pagenumber,Integer pageSize){ try { Sort.Direction sortlast; if("desc".equals(sort.toLowerCase())){ sortlast = Sort.Direction.DESC; }else{ sortlast = Sort.Direction.ASC; } Sort orders = new Sort(sortlast, "employeeId"); Pageable pageable = new PageRequest(pagenumber, pageSize, orders); ? Page<Employee> employeePage = employeeReposiroty.findAll(pageable); List<Employee> employeeList = employeePage.getContent(); return employeeList; }catch (Exception e){ e.printStackTrace(); return null; } } /** * 自定义拓展jpa,根据用户名查找单个用户 * @param username * @return */ @GetMapping(value = "employee/find/{username}") @ApiOperation(value = "查询用户信息",notes = "根据用户登录名查询该用户信息") @ApiImplicitParam(paramType = "path",name = "username",value = "用户登录名",required = true,dataType = "String") public Employee findByUsername(@PathVariable("username") String username){ List<Employee> employeeList = employeeReposiroty.findByUserNameOrderByEmployeeIdAsc(username); if (employeeList != null && !employeeList.isEmpty()){ return employeeList.get(0); } return null; } }
注意: 在后台采用对象接收参数时,Swagger自带的工具采用的是JSON传参, 测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。
/** * @program: jpademo * @description: Employee * @create 2018-10-23 10:20 */ ? @Data @Entity @Table(name = "employee") @ApiModel(value = "用户对象模型") public class Employee { ? @Id @GeneratedValue(strategy = GenerationType.IDENTITY) @Column(name = "employee_id") @Min(value = 1,groups = Employee.Children.class) private Integer employeeId; ? @Column(name = "user_name",length = 20,nullable = true) @ApiModelProperty(value = "userName",required = true) private String userName; ? @Column(nullable = true) @Size(min = 0,max = 65,message = "年龄超过范围限制",groups = Employee.Audit.class) @ApiModelProperty(value = "age",required = true) private Integer age; ? @Column(name="gra_id") @ApiModelProperty(value = "graId",required = true) //@Digits(integer = 12,fraction = 4) //限制必须为一个小数,且整数部分的 位数 不能超过integer,小数部分的 位数 不能超过fraction private Integer graId; ? public interface Audit{}; ? public interface Children{}; ? }