Swagger使用

1、描述

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

作用：

1.接口的文档在线自动生成。

2.功能测试。

2、运用

a) maven导入Swagger

<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>

b) 创建Swagger2配置类

/**

* @program: jpademo

* @description: Swagger

* @author: ZengGuangfu

* @create 2018-10-24 10:12

*/​@Configuration@EnableSwagger2publicclassSwagger{​@BeanpublicDocketdocket(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.springbootjpa.jpademo.controller")).paths(PathSelectors.any()).build();}​publicApiInfoapiInfo(){returnnewApiInfoBuilder().title("利用swagger2构建的API文档").description("用restful风格写接口").termsOfServiceUrl("").version("1.0").build();}}

如上所示，docket() 方法创建Docket的Bean对象，apiInfo()则是创建ApiInfo的基本信息。

链式方法解析：

3、注解及其说明

@Api : 用在类上，说明该类的主要作用。

@ApiOperation：用在方法上，给API增加方法说明。

@ApiImplicitParams : 用在方法上，包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

apiParam.png

@ApiResponses：用于表示一组响应。

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

​ lcode：数字，例如400

​ lmessage：信息，例如"请求参数没填好"

​ lresponse：抛出异常的类

@ApiModel：用在返回对象类上，描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

​ l@ApiModelProperty：描述一个model的属性

例子：

packagecom.example.springbootjpa.jpademo.controller;​importcom.example.springbootjpa.jpademo.config.utils.SysNode;importcom.example.springbootjpa.jpademo.dao.EmployeeReposiroty;importcom.example.springbootjpa.jpademo.pojo.Employee;importio.swagger.annotations.Api;importio.swagger.annotations.ApiImplicitParam;importio.swagger.annotations.ApiImplicitParams;importio.swagger.annotations.ApiOperation;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.data.domain.*;importorg.springframework.data.jpa.domain.Specification;importorg.springframework.lang.Nullable;importorg.springframework.validation.annotation.Validated;importorg.springframework.web.bind.annotation.*;​importjavax.persistence.criteria.CriteriaBuilder;importjavax.persistence.criteria.CriteriaQuery;importjavax.persistence.criteria.Predicate;importjavax.persistence.criteria.Root;importjavax.validation.groups.Default;importjava.util.ArrayList;importjava.util.List;​/**

* @program: jpademo

* @description: EmployeeController

* @author: ZengGuangfu

* @create 2018-10-23 11:07

*/​@RestController@RequestMapping("emp")@Api(value="用户管理类")publicclassEmployeeController{​@AutowiredprivateEmployeeReposiroty 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)publicStringinsert(Employee employee){Employee employee1=employeeReposiroty.save(employee);if(employee1!=null){returnSysNode.Judge.SUCCESS.getResult();}else{returnSysNode.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)publicStringdelete(@PathVariable("id")Integer id){try{employeeReposiroty.deleteById(id);returnSysNode.Judge.SUCCESS.getResult();}catch(Exception e){e.printStackTrace();returnSysNode.Judge.FAILD.getResult();}}​/**

      * 修改单个成员

      * @param employee

      * @return

      */@PutMapping(value="employee/{id}")@ApiOperation(value="修改用户信息",notes="根据成员id修改单个用户")@ApiImplicitParam(paramType="path",name="id",value="用户id",required=true,dataType="Integer")publicStringupdate(Employee employee){/**

          * save方法如果参数属性缺失，会导致原本存在的数据为null

          */Employee employee1=employeeReposiroty.saveAndFlush(employee);if(employee1!=null){returnSysNode.Judge.SUCCESS.getResult();}else{returnSysNode.Judge.FAILD.getResult();}}​/**

      * 获取所有成员,升序排列

      * @return

      */@GetMapping(value="employee/sort")@ApiOperation(value="查询全部用户",notes="默认根据升序查询全部用户信息")publicList<Employee>findAll(){Sort orders=newSort(Sort.Direction.DESC,"employeeId");List<Employee>employeeList=employeeReposiroty.findAll(orders);returnemployeeList;}​/**

    * 获取所有成员,升序排列

    * @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)})publicList<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=newSort(sortlast,"employeeId");Pageable pageable=newPageRequest(pagenumber,pageSize,orders);​                    Page<Employee>employeePage=employeeReposiroty.findAll(pageable);List<Employee>employeeList=employeePage.getContent();returnemployeeList;}catch(Exception e){e.printStackTrace();returnnull;}}/**

    * 自定义拓展jpa，根据用户名查找单个用户

    * @param username

    * @return

    */@GetMapping(value="employee/find/{username}")@ApiOperation(value="查询用户信息",notes="根据用户登录名查询该用户信息")@ApiImplicitParam(paramType="path",name="username",value="用户登录名",required=true,dataType="String")publicEmployeefindByUsername(@PathVariable("username")String username){List<Employee>employeeList=employeeReposiroty.findByUserNameOrderByEmployeeIdAsc(username);if(employeeList!=null&&!employeeList.isEmpty()){returnemployeeList.get(0);}returnnull;}​/**

    * 测试用

    * @return

    */@GetMapping(value="employee/grade")publicList<Object[]>findEmployeeAndGrade(){Pageable pageable=newPageRequest(0,3);​        Page<Object[]>page=employeeReposiroty.findEmployeeAndGrade(pageable);System.out.println(page.getTotalElements()+"----------结果总数------------");System.out.println(page.getTotalPages()+"--------根据pageSize的总页数-----------");System.out.println(page.getNumber()+"--------当前页数，pageNumber----------");System.out.println(page.getNumberOfElements()+"--------当前页有几个数据--------");System.out.println(page.getSize()+"---------PageSize-------------");System.out.println(page.getSort()+"---------排序方式，没有则是'UNSORTED'----------");​        List<Object[]>objects=page.getContent();returnobjects;}}

4、测试登录 localhost:8080/swagger-ui.html

swagger-ui.png

API 操作测试，修改

testParam.png

testResult.png

5、@ApiModel 接收对象传参

注意： 在后台采用对象接收参数时，Swagger自带的工具采用的是JSON传参， 测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。

例子：

/**

* @program: jpademo

* @description: Employee

* @author: ZengGuangfu

* @create 2018-10-23 10:20

*/​​@Getter@Setter@Data@Entity@Table(name="employee")@ApiModel(value="用户对象模型")publicclassEmployee{​@Id@GeneratedValue(strategy=GenerationType.IDENTITY)@Column(name="employee_id")@Min(value=1,groups=Employee.Children.class)privateInteger employeeId;​@Column(name="user_name",length=20,nullable=true)@ApiModelProperty(value="userName",required=true)privateString userName;​@Column(nullable=true)@Size(min=0,max=65,message="年龄超过范围限制",groups=Employee.Audit.class)@ApiModelProperty(value="age",required=true)privateInteger age;​@Column(name="gra_id")@ApiModelProperty(value="graId",required=true)//@Digits(integer = 12,fraction = 4)  //限制必须为一个小数，且整数部分的 位数 不能超过integer，小数部分的 位数 不能超过fractionprivateInteger graId;​publicinterfaceAudit{};​publicinterfaceChildren{};​}

作者：茧铭

链接：https://www.jianshu.com/p/a0caf58b3653

来源：简书

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。