[关闭]
@BookThief 2016-05-20T06:18:46.000000Z 字数 1828 阅读 3386

Swagger

Swagger


接口编码规范

其中 134 建议作为接口编码时必须项

  1. // 0、 方法描述
  2. @ApiOperation(value = "getUser", nickname = "getUser")
  3. // 1、 请求类型
  4. @RequestMapping(method = RequestMethod.GET, // 1-1、 请求方法
  5. path = "/demo/user", // 1-2、 请求URL
  6. produces = "application/json") // 1-3、 相应数据类型
  7. // 2、 请求参数描述
  8. @ApiImplicitParams({
  9. @ApiImplicitParam(name = "name", // 2-1、 参数名
  10. required = false, // 2-3、 是否必须
  11. dataType = "string", // 2-4、 数据类型 (类名或基本类型)
  12. paramType = "query", // 2-5、 参数类型 ( path, query, body, header, form)
  13. defaultValue = "Niklas", // 2-6、 参数默认值
  14. value = "用户名") // 2-7、 字段描述
  15. })
  16. // 3、 状态码描述: code 状态码 message 描述 response 返回值类型
  17. @ApiResponses(value = {
  18. @ApiResponse(code = 200, message = "Success", response = User.class),
  19. @ApiResponse(code = 401, message = "Unauthorized"),
  20. @ApiResponse(code = 403, message = "Forbidden"),
  21. @ApiResponse(code = 404, message = "Not Found"),
  22. @ApiResponse(code = 500, message = "Failure")})
  23. public User getUser(
  24. // 4、 请求参数描述,与2基本相同。可选参数少,但直接对应参数,比较直观。建议使用 4 进行参数描述。
  25. // Object 类型,需在该对象内设置 @ApiModel @ApiModelProperty 等注解。
  26. @RequestParam(value = "phone", defaultValue = "15510967745") String phone,
  27. @RequestParam(value = "status") int status, User testUser) {
  28. User user = new User();
  29. user.setPhone(phone);
  30. user.setEmail(testUser.getEmail());
  31. user.setPassword(testUser.getPassword());
  32. user.setStatus(status);
  33. return user;
  34. }

对象参数注解

  1. @ApiModel(value = "User", // 模型名称
  2. description = "the base info of user", // 描述
  3. parent = BaseIdEntity.class) // 父类
  4. @Table("t_user")
  5. public class User extends BaseIdEntity {
  6. /**
  7. * 手机号
  8. */
  9. /* 属性描述,常用参数如下:
  10. value: 参数名描述
  11. notes: 同value
  12. dataType: 参数类型
  13. require: 是否必须
  14. hidden: 是否在SwaggerJson内显示
  15. */
  16. @ApiModelProperty(notes = "用户手机号", required = false)
  17. @Column
  18. private String phone;
  19. /**
  20. * email
  21. */
  22. @NotEmpty
  23. @Column
  24. @ApiModelProperty(notes = "用户Email", required = true)
  25. private String email;
  26. /**
  27. * 密文密码
  28. */
  29. @Column
  30. @ApiModelProperty(notes = "密文密码", required = false)
  31. private String password;
  32. /**
  33. * 用户是否被屏蔽
  34. */
  35. @Column
  36. @ApiModelProperty(notes = "用户是否被屏蔽", required = false)
  37. private Integer status;
  38. // ... getter() & setter() ...
  39. }

『swagger-ui』 界面

访问地址: http://{ipaddress:port}/swagger/index.html

添加新批注
在作者公开此批注前,只有你和作者可见。
回复批注