1、若依系统会自带有swagger生成接口文档,登录若依系统后可以在
这里查看系统的接口demo。
如果想更改这个接口文档的样式可以参考地址:
https://blog.csdn.net/qq_22734863/article/details/113341869
2、我修改样式的方法
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
然后在项目中全局搜索:将swagger-ui.html修改成doc.html。我的一共是修改了两个地方分别是:
3、swagger使用的方法可以参考:
添加链接描述
(1)
@Api :请求类的说明
@Api:放在请求的类上,与 @Controller 并列,说明类的作用,如用户模块,订单类等。
tags=“说明该类的作用”
value=“该参数没什么意义,所以不需要配置”
举例:
@Api(tags = “账户相关模块”)
@RestController
@RequestMapping("/api/account")
public class AccountController {
//TODO
}
(2)
@ApiOperation:方法的说明
@ApiOperation:“用在请求的方法上,说明方法的作用”
value=“说明方法的作用”
notes=“方法的备注说明”
举例:
@ApiOperation(value = “修改密码”, notes = “方法的备注说明,如果有可以写在这里”)
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
@RequestBody @Valid PasswordModel passwordModel) {
//TODO
}
(3)
@ApiImplicitParams、@ApiImplicitParam:方法参数的说明
@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParam:对单个参数的说明
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)–> 请求参数的获取:@PathVariable
· body(请求体)–> @RequestBody User user
· form(普通表单提交)
dataType:参数类型,默认String,其它值dataType=“int”
defaultValue:参数的默认值
举例:
@ApiOperation(value=“用户登录”,notes=“随边说点啥”)
@ApiImplicitParams({
@ApiImplicitParam(name=“mobile”,value=“手机号”,required=true,paramType=“form”),
@ApiImplicitParam(name=“password”,value=“密码”,required=true,paramType=“form”),
@ApiImplicitParam(name=“age”,value=“年龄”,required=true,paramType=“form”,dataType=“Integer”)
})
@PostMapping("/login")
public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//TODO
return AjaxResult.OK();
}
单个参数举例
@ApiOperation(“根据部门Id删除”)
@ApiImplicitParam(name=“depId”,value=“部门id”,required=true,paramType=“query”)
@GetMapping("/delete")
public AjaxResult delete(String depId) {
//TODO
}
(4)
@ApiResponses、@ApiResponse:方法返回值的说明
@ApiResponses:方法返回对象的说明
@ApiResponse:每个参数的说明
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
举例:
@ApiOperation(value = “修改密码”, notes = “方法的备注说明,如果有可以写在这里”)
@ApiResponses({
@ApiResponse(code = 400, message = “请求参数没填好”),
@ApiResponse(code = 404, message = “请求路径找不到”)
})
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
@RequestBody @Valid PasswordModel passwordModel) {
//TODO
}
(5)
@ApiModel:用于JavaBean上面,表示一个JavaBean
@ApiModel:用于JavaBean的类上面,表示此 JavaBean 整体的信息
(这种一般用在post创建的时候,使用 @RequestBody 这样的场景,请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )
(6)
@ApiModelProperty:用在JavaBean的属性上面,说明属性的含义
@ApiModel和 @ApiModelProperty举例:
@ApiModel(“修改密码所需参数封装类”)
public class PasswordModel
{
@ApiModelProperty(“账户Id”)
private String accountId;
//TODO
}
然后以一个我自己写的Controller为例参考下:
然后在系统的界面可以看到这个接口文档:
在浏览器中输入:
localhost:8080/ruoyi-admin/doc.html
同样可以看到接口文档