swagger使用详解

例⼦：

package com.swaggerTest.controller;

import org.springframework.stereotype.Controller;import org.springframework.util.StringUtils;

import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import org.springframework.web.bind.annotation.RequestParam;import org.springframework.web.bind.annotation.ResponseBody;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation; /**

* ⼀个⽤来测试swagger注解的控制器

* 注意@ApiImplicitParam的使⽤会影响程序运⾏，如果使⽤不当可能造成控制器收不到消息 *

* @author SUNF */

@Controller

@RequestMapping(\"/say\")

@Api(value = \"SayController|⼀个⽤来测试swagger注解的控制器\")public class SayController {

@ResponseBody

@RequestMapping(value =\"/getUserName\

@ApiOperation(value=\"根据⽤户编号获取⽤户姓名\仅1和2有正确返回\")

@ApiImplicitParam(paramType=\"query\⽤户编号\\"Integer\")

public String getUserName(@RequestParam Integer userNumber){ if(userNumber == 1){

return \"张三丰\"; } else if(userNumber == 2){ return \"慕容复\"; } else{ return \"未知\"; } } @ResponseBody @RequestMapping(\"/updatePassword\") @ApiOperation(value=\"修改⽤户密码\根据⽤户id修改密码\") @ApiImplicitParams({ @ApiImplicitParam(paramType=\"query\⽤户ID\\"Integer\"), @ApiImplicitParam(paramType=\"query\旧密码\\"String\"), @ApiImplicitParam(paramType=\"query\新密码\\"String\") }) public String updatePassword(@RequestParam(value=\"userId\") Integer userId,@RequestParam(value=\"password\") String password, @RequestParam(value=\"newPassword\") String newPassword){ if(userId <= 0 || userId > 2){ return \"未知的⽤户\"; } if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){ return \"密码不能为空\"; } if(password.equals(newPassword)){ return \"新旧密码不能相同\"; } return \"密码修改成功!\"; }} 如上图，可以看到暴漏出来的控制器信息，点击进⼊可以看到详细信息。两个注意点：1. paramType会直接影响程序的运⾏期，如果paramType与⽅法参数获取使⽤的注解不⼀致，会直接影响到参数的接收。例如：使⽤Sawgger UI进⾏测试，接收不到！2. 还有⼀个需要注意的地⽅：Conntroller中定义的⽅法必须在@RequestMapper中显⽰的指定RequestMethod类型，否则SawggerUi会默认为全类型皆可访问， API列表中会⽣成多条项⽬。如上图：updatePassword()未指定requestMethod，结果⽣成了7条API信息。所以如果没有特殊需求，建议根据实际情况加上requestMethod。 5：Swagger UI⾯板说明paramType：指定参数放在哪个地⽅6：参考 ---------------------------------------------------------------------------------------7：接收对象传参的例⼦在POJO上增加

package com.zhongying.api.model.base;

import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty; /**

* 医⽣对象模型，不要使⽤该类 * @author SUNF * */

@ApiModel(value=\"医⽣对象模型\")public class DemoDoctor{

@ApiModelProperty(value=\"id\" ,required=true) private Integer id;

@ApiModelProperty(value=\"医⽣姓名\" ,required=true) private String name;

public Integer getId() { return id; }

public void setId(Integer id) { this.id = id; }

public String getName() { return name; }

public void setName(String name) { this.name = name; }

@Override

public String toString() {

return \"DemoDoctor [id=\" + id + \ } }

注意： 在后台采⽤对象接收参数时，Swagger⾃带的⼯具采⽤的是JSON传参，@RequestBody,正常运⾏采⽤form或URL提交时候请删除。

package com.zhongying.api.controller.app;

import java.util.ArrayList;import java.util.List;

import javax.servlet.http.HttpServletRequest;

import org.springframework.stereotype.Controller;

import org.springframework.web.bind.annotation.RequestBody;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import org.springframework.web.bind.annotation.RequestParam;import org.springframework.web.bind.annotation.ResponseBody;

import com.github.pagehelper.PageInfo;

import com.zhongying.api.exception.HttpStatus401Exception;import com.zhongying.api.model.base.DemoDoctor;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation; /**

* 医⽣类（模拟） * @author SUNF */

@RequestMapping(\"/api/v1\")@Controller

@Api(value = \"DoctorTestController-医⽣信息接⼝模拟\")public class DoctorTestController { /**

* 添加医⽣ *

* 在使⽤对象封装参数进⾏传参时，需要在该对象添加注解，将其注册到swagger中 * @link com.zhongying.api.model.base.DemoDoctor

测试时需要在参数上加⼊ *

* 注意： 在后台采⽤对象接收参数时，Swagger⾃带的⼯具采⽤的是JSON传参，

* 测试时需要在参数上加⼊@RequestBody,正常运⾏采⽤form或URL提交时候请删除。 *

* @param doctor 医⽣类对象 * @return

* @throws Exception */

@ResponseBody

@RequestMapping(value=\"/doctor\ @ApiOperation(value=\"添加医⽣信息\

public String addDoctor(@RequestBody DemoDoctor doctor) throws Exception{ if(null == doctor || doctor.getId() == null){

throw new HttpStatus401Exception(\"添加医⽣失败\未知原因\请联系管理员\"); } try {

System.out.println(\"成功----------->\"+doctor.getName()); } catch (Exception e) {

throw new HttpStatus401Exception(\"添加医⽣失败\未知原因\请联系管理员\"); }

return doctor.getId().toString(); } /**

* 删除医⽣

* @param doctorId 医⽣ID * @return */

@ResponseBody

@RequestMapping(value=\"/doctor/{doctorId}\ @ApiOperation(value=\"删除医⽣信息\

@ApiImplicitParam(paramType=\"query\医⽣ID\ public String deleteDoctor(@RequestParam Integer doctorId){ if(doctorId > 2){

return \"删除失败\"; }

return \"删除成功\"; } /**

* 修改医⽣信息

* @param doctorId 医⽣ID * @param doctor 医⽣信息 * @return

* @throws HttpStatus401Exception */

@ResponseBody

@RequestMapping(value=\"/doctor/{doctorId}\ @ApiOperation(value=\"修改医⽣信息\

@ApiImplicitParam(paramType=\"query\医⽣ID\

public String updateDoctor(@RequestParam Integer doctorId, @RequestBody DemoDoctor doctor) throws HttpStatus401Exception{ if(null == doctorId || null == doctor){

throw new HttpStatus401Exception(\"修改医⽣信息失败\不能为空\请修改\"); }

if(doctorId > 5 ){

throw new HttpStatus401Exception(\"医⽣不存在\错误的ID\请更换ID\"); }

System.out.println(doctorId); System.out.println(doctor); return \"修改成功\"; } /**

* 获取医⽣详细信息

* @param doctorId 医⽣ID * @return

* @throws HttpStatus401Exception */

@ResponseBody

@RequestMapping(value=\"/doctor/{doctorId}\ @ApiOperation(value=\"获取医⽣详细信息\仅返回姓名..\")

@ApiImplicitParam(paramType=\"query\医⽣ID\ public DemoDoctor getDoctorDetail(@RequestParam Integer doctorId) throws HttpStatus401Exception{ System.out.println(doctorId); if(null == doctorId){

throw new HttpStatus401Exception(\"查看医⽣信息失败\未知原因\请联系管理员\"); }

if(doctorId > 3){

throw new HttpStatus401Exception(\"医⽣不存在\错误的ID\请更换ID\"); }

DemoDoctor doctor = new DemoDoctor(); doctor.setId(1);

doctor.setName(\"测试员\");

return doctor; } /**

* 获取医⽣列表

* @param pageIndex 当前页数 * @param pageSize 每页记录数 * @param request * @return

* @throws HttpStatus401Exception */

@ResponseBody

@RequestMapping(value=\"/doctor\ @ApiOperation(value=\"获取医⽣列表\⽬前⼀次全部取，不分页\") @ApiImplicitParams({

@ApiImplicitParam(paramType=\"header\

@ApiImplicitParam(paramType=\"query\当前页数\ @ApiImplicitParam(paramType=\"query\每页记录数\ })

public PageInfo getDoctorList(@RequestParam(value = \"pageIndex\ @RequestParam(value = \"pageSize\ HttpServletRequest request) throws HttpStatus401Exception{

String token = request.getHeader(\"token\"); if(null == token){

throw new HttpStatus401Exception(\"没有权限\没有权限\请查看操作⽂档\"); }

if(null == pageSize){

throw new HttpStatus401Exception(\"每页记录数不粗安在\不存在pageSize\请查看操作⽂档\"); }

DemoDoctor doctor1 = new DemoDoctor(); doctor1.setId(1);

doctor1.setName(\"测试员1\");

DemoDoctor doctor2 = new DemoDoctor(); doctor2.setId(2);

doctor2.setName(\"测试员2\");

List doctorList = new ArrayList(); doctorList.add(doctor1); doctorList.add(doctor2);

return new PageInfo(doctorList); } }

增加header:

现在很多请求需要在header增加额外参数，可以参考getDoctorList()的做法，使⽤request接收原⽂地址：https://blog.csdn.net/xiaoxinxin123456789/article/details/83994859