Swagger使用

1、描述

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。

作用：

1.接口的文檔在線自動(dòng)生成。

2.功能測(cè)試。

2、運(yùn)用

a) maven導(dǎo)入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) 創(chuàng)建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構(gòu)建的API文檔").description("用restful風(fēng)格寫接口").termsOfServiceUrl("").version("1.0").build();}}

如上所示，docket() 方法創(chuàng)建Docket的Bean對(duì)象，apiInfo()則是創(chuàng)建ApiInfo的基本信息。

鏈?zhǔn)椒椒ń馕觯?/p>

3、注解及其說明

@Api : 用在類上，說明該類的主要作用。

@ApiOperation：用在方法上，給API增加方法說明。

@ApiImplicitParams : 用在方法上，包含一組參數(shù)說明。

@ApiImplicitParam：用來注解來給方法入?yún)⒃黾诱f明。

apiParam.png

@ApiResponses：用于表示一組響應(yīng)。

@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息

? lcode：數(shù)字，例如400

? lmessage：信息，例如"請(qǐng)求參數(shù)沒填好"

? lresponse：拋出異常的類

@ApiModel：用在返回對(duì)象類上，描述一個(gè)Model的信息（一般用在請(qǐng)求參數(shù)無法使用@ApiImplicitParam注解進(jìn)行描述的時(shí)候）

? l@ApiModelProperty：描述一個(gè)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="新增一個(gè)用戶",notes="新增之后返回對(duì)象")@ApiImplicitParam(paramType="query",name="employee",value="用戶",required=true)@ApiResponse(code=400,message="參數(shù)沒有填好",response=String.class)publicStringinsert(Employee employee){Employee employee1=employeeReposiroty.save(employee);if(employee1!=null){returnSysNode.Judge.SUCCESS.getResult();}else{returnSysNode.Judge.FAILD.getResult();}}?/**

? ? ? * 刪除單個(gè)用戶

? ? ? * @param id

? ? ? * @return

? ? ? */@DeleteMapping(value="employee/{id}")@ApiOperation(value="刪除用戶",notes="根據(jù)成員id刪除單個(gè)用戶")@ApiImplicitParam(paramType="path",name="id",value="用戶id",required=true,dataType="Integer")@ApiResponse(code=400,message="參數(shù)沒有填好",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();}}?/**

? ? ? * 修改單個(gè)成員

? ? ? * @param employee

? ? ? * @return

? ? ? */@PutMapping(value="employee/{id}")@ApiOperation(value="修改用戶信息",notes="根據(jù)成員id修改單個(gè)用戶")@ApiImplicitParam(paramType="path",name="id",value="用戶id",required=true,dataType="Integer")publicStringupdate(Employee employee){/**

? ? ? ? ? * save方法如果參數(shù)屬性缺失，會(huì)導(dǎo)致原本存在的數(shù)據(jù)為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="查詢?nèi)坑脩?,notes="默認(rèn)根據(jù)升序查詢?nèi)坑脩粜畔?)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="分頁數(shù)",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，根據(jù)用戶名查找單個(gè)用戶

? ? * @param username

? ? * @return

? ? */@GetMapping(value="employee/find/{username}")@ApiOperation(value="查詢用戶信息",notes="根據(jù)用戶登錄名查詢?cè)撚脩粜畔?)@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;}?/**

? ? * 測(cè)試用

? ? * @return

? ? */@GetMapping(value="employee/grade")publicList<Object[]>findEmployeeAndGrade(){Pageable pageable=newPageRequest(0,3);?? ? ? ? Page<Object[]>page=employeeReposiroty.findEmployeeAndGrade(pageable);System.out.println(page.getTotalElements()+"----------結(jié)果總數(shù)------------");System.out.println(page.getTotalPages()+"--------根據(jù)pageSize的總頁數(shù)-----------");System.out.println(page.getNumber()+"--------當(dāng)前頁數(shù)，pageNumber----------");System.out.println(page.getNumberOfElements()+"--------當(dāng)前頁有幾個(gè)數(shù)據(jù)--------");System.out.println(page.getSize()+"---------PageSize-------------");System.out.println(page.getSort()+"---------排序方式，沒有則是'UNSORTED'----------");?? ? ? ? List<Object[]>objects=page.getContent();returnobjects;}}

4、測(cè)試登錄 localhost:8080/swagger-ui.html

swagger-ui.png

API 操作測(cè)試，修改

testParam.png

testResult.png

5、@ApiModel 接收對(duì)象傳參

注意： 在后臺(tái)采用對(duì)象接收參數(shù)時(shí)，Swagger自帶的工具采用的是JSON傳參， 測(cè)試時(shí)需要在參數(shù)上加入@RequestBody,正常運(yùn)行采用form或URL提交時(shí)候請(qǐng)刪除。

例子：

/**

* @program: jpademo

* @description: Employee

* @author: ZengGuangfu

* @create 2018-10-23 10:20

*/??@Getter@Setter@Data@Entity@Table(name="employee")@ApiModel(value="用戶對(duì)象模型")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)? //限制必須為一個(gè)小數(shù)，且整數(shù)部分的 位數(shù) 不能超過integer，小數(shù)部分的 位數(shù) 不能超過fractionprivateInteger graId;?publicinterfaceAudit{};?publicinterfaceChildren{};?}

作者：繭銘

鏈接：http://www.itdecent.cn/p/a0caf58b3653

來源：簡書

著作權(quán)歸作者所有。商業(yè)轉(zhuǎn)載請(qǐng)聯(lián)系作者獲得授權(quán)，非商業(yè)轉(zhuǎn)載請(qǐng)注明出處。