Swagger 常用注解使用详解

分手后的思念是犯贱 2021-10-19 08:22 433阅读 0赞

刚开始的时候，在controller层使用@RequestParam的时候，发现这个参数是必须要输入值的，但是我们有时候必须查询的时候允许参数为空，使用这个注解就不行了。

在集成了swagger2后，找了半天的原因，发现使用@ApiImplicitParam这个注解可以解决这个问题。

![aHR0cHM6Ly9pbWFnZXMyMDE3LmNuYmxvZ3MuY29tL2Jsb2cvOTk4MzQyLzIwMTcxMS85OTgzNDItMjAxNzExMjkyMDM4MTQ1NzMtMjM1MzIyNzc0LnBuZw][]

对应下面的参数。

所以我们可以使用这个注解来解决我们所遇到的参考为空的问题。

而且已经集成了swagger2，所以我们尽量来使用这个注解吧。

说明：   
1.这里使用的版本：springfox-swagger2（2.4）springfox-swagger-ui （2.4）   
2.这里是说明常用注解的含义和基本用法（也就是说已经对swagger进行集成完成）   
没有集成的请参见   
[SpringBoot集成springfox-swagger2构建restful API][SpringBoot_springfox-swagger2_restful API]   
[SpringMVC集成springfox-swagger2构建restful API][SpringMVC_springfox-swagger2_restful API]   
[官网WIKI][WIKI]   
常用注解：   
\- @Api()用于类；   
表示标识这个类是swagger的资源   
\- @ApiOperation()用于方法；   
表示一个http请求的操作   
\- @ApiParam()用于方法，参数，字段说明；   
表示对参数的添加元数据（说明或是否必填等）   
\- @ApiModel()用于类   
表示对类进行说明，用于参数用实体类接收   
\- @ApiModelProperty()用于方法，字段   
表示对model属性的说明或者数据操作更改   
\- @ApiIgnore()用于类，方法，方法参数   
表示这个方法或者类被忽略   
\- @ApiImplicitParam() 用于方法   
表示单独的请求参数   
\- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明：   
@Api()   
用于类；表示标识这个类是swagger的资源   
tags–表示说明   
value–也是说明，可以使用tags替代   
但是tags如果有多个值，会生成多个list

1.  `@Api(value="用户controller",tags={"用户操作接口"})`
2.  `@RestController`
3.  `public class UserController {`
4.   
5.  `}`

效果图：   
![这里写图片描述][SouthEast]

@ApiOperation() 用于方法；表示一个http请求的操作   
value用于方法描述   
notes用于提示内容   
tags可以重新分组（视情况而用）   
@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）   
name–参数名   
value–参数说明   
required–是否必填

1.  `@Api(value="用户controller",tags={"用户操作接口"})`
2.  `@RestController`
3.  `public class UserController {`
4.  `@ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")`
5.  `@GetMapping("/getUserInfo")`
6.  `public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {`
7.  `// userService可忽略，是业务逻辑`
8.  `User user = userService.getUserInfo();`
9.   
10. `return user;`
11. `}`
12. `}`

效果图：   
![这里写图片描述][SouthEast 1]

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收   
value–表示对象名   
description–描述   
都可省略   
@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改   
value–字段说明   
name–重写属性名字   
dataType–重写属性类型   
required–是否必填   
example–举例说明   
hidden–隐藏

1.  `@ApiModel(value="user对象",description="用户对象user")`
2.  `public class User implements Serializable{`
3.  `private static final long serialVersionUID = 1L;`
4.  `@ApiModelProperty(value="用户名",name="username",example="xingguo")`
5.  `private String username;`
6.  `@ApiModelProperty(value="状态",name="state",required=true)`
7.  `private Integer state;`
8.  `private String password;`
9.  `private String nickName;`
10. `private Integer isDeleted;`
11.  
12. `@ApiModelProperty(value="id数组",hidden=true)`
13. `private String[] ids;`
14. `private List<String> idList;`
15. `//省略get/set`
16. `}`

1.  `@ApiOperation("更改用户信息")`
2.  `@PostMapping("/updateUserInfo")`
3.  `public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){`
4.   
5.  `int num = userService.updateUserInfo(user);`
6.  `return num;`
7.  `}`

效果图：   
![这里写图片描述][SouthEast 2]

![这里写图片描述][SouthEast 3]

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上   
比较简单, 这里不做举例

@ApiImplicitParam() 用于方法   
表示单独的请求参数   
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam   
name–参数ming   
value–参数说明   
dataType–数据类型   
paramType–参数类型   
example–举例说明

1.  `@ApiOperation("查询测试")`
2.  `@GetMapping("select")`
3.  `//@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")`
4.  `@ApiImplicitParams({`
5.  `@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),`
6.  `@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})`
7.  `public void select(){`
8.   
9.  `}`

效果图：   
![这里写图片描述][SouthEast 4]

[aHR0cHM6Ly9pbWFnZXMyMDE3LmNuYmxvZ3MuY29tL2Jsb2cvOTk4MzQyLzIwMTcxMS85OTgzNDItMjAxNzExMjkyMDM4MTQ1NzMtMjM1MzIyNzc0LnBuZw]: /images/20211018/400aa8cc8f8b474d9282f1499b50ebe3.png
[SpringBoot_springfox-swagger2_restful API]: http://blog.csdn.net/u014231523/article/details/54562695
[SpringMVC_springfox-swagger2_restful API]: http://blog.csdn.net/u014231523/article/details/54411026
[WIKI]: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview
[SouthEast]: /images/20211018/70f98967a19842568d180003756dbb40.png
[SouthEast 1]: /images/20211018/a86c7e174eea4ee7a68725de9c2b17a8.png
[SouthEast 2]: /images/20211018/0c93e920c23c410590a092592183a2e7.png
[SouthEast 3]: /images/20211018/91636c2429bf497ca5f376e750282c46.png
[SouthEast 4]: /images/20211018/07008606fb564470896bb28b47c76f48.png