一.简介

1.什么是swagger

2.swagger的特征

3.swagger依赖包

二.swagger常用注解

1.@Api

2.@ApiOperation

3.@ApiParam

4.@ApiImplicitParams、@ApiImplicitParam

5.@ApiResponses、@ApiResponse

6.@ApiModel、@ApiModelProperty

7.@PathVariable

三.注解使用注意点

一.简介

1.什么是swagger

Swagger是一个开放源代码软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用RESTful Web服务。尽管大多数用户通过Swagger UI工具识别Swagger，但是Swagger工具集包括对自动文档，代码生成和测试用例生成的支持。

2.swagger的特征

1. 通过代码和注释自动生成文档。在Swagger框架下，开发人员可对服务进行归类说明，对方法，模型，返回结果等进行详细说明。方便开发人员在编写代码的同时，编写文档信息。自动生成，只需很少的编辑工作，就能获得完整的REST APIs文档

2. 提供了UI界面。既展示接口信息，又提供了参数校验，测试功能

3. 形成了文档规范，支持不同的语言

4. 提供丰富的组件。

3.swagger依赖包

<!--swagger2--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId></dependency>

二.swagger常用注解

1.@Api

@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

属性	描述
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

示例代码:

@Controller
@Slf4j
@RequestMapping("/user")
@Api(tags = "人员信息 API", description = "提供人员信息相关的 Rest API")
public class UserController extends BaseController {}

2.@ApiOperation

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

主要属性:

属性	描述
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code	http的状态码默认 200
extensions	扩展属性

3.@ApiParam

@ApiParam作用于请求方法上，定义api参数的注解。

主要属性:

属性	描述
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

代码示例:

public ResponseEntity<User> getUserById(@ApiParam(value = "ID of user that needs to be fetched", allowableValues = "range[1,10]", required = true)@PathVariable("UserId") Long userId)

4.@ApiImplicitParams、@ApiImplicitParam

@ApiImplicitParams、@ApiImplicitParam 都可以定义参数.

(1).@ApiImplicitParams：用在请求的方法上，包含一组参数说明

(2).@ApiImplicitParam：对单个参数的说明

主要属性：

属性	描述
name	参数名
value	参数的说明、描述
required	参数是否必须必填
paramType	参数放在哪个地方 query --> 请求参数的获取：@RequestParam header --> 请求参数的获取：@RequestHeader path（用于restful接口）--> 请求参数的获取：@PathVariable body（请求体）--> @RequestBody User user form（普通表单提交）
dataType	参数类型，默认String，其它值dataType="Integer"
defaultValue	参数的默认值

代码示例:

提示:根据dataTtype属性的描述我们的"手机号","密码"都是"String"类型所以我们将其省略

/*** <pre>*  登录API接口* </pre>** @since 2022-06-10*/
@ApiImplicitParams({//参数效验@ApiImplicitParam(name="phonenum",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 ApiResult login(@RequestParam String mobile, @RequestParam String password,@RequestParam Integer age){//...return JsonResult.ok(map);}

5.@ApiResponses、@ApiResponse

@ApiResponses、@ApiResponse进行方法返回对象的说明。

主要属性：

属性	描述
code	数字，例如400
message	信息，例如"请求参数没填好"
response	抛出异常的类

代码示例:

@ApiResponses({@ApiResponse(code = 200, message = "请求成功"),@ApiResponse(code = 400, message = "请求参数没填好"),@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")}) @ResponseBody@RequestMapping("/user")public ApiResult getUser(@RequestParam String userId) {...}

6.@ApiModel、@ApiModelProperty

@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty用来描述一个Model的属性

使用场景

@ApiModel 用在模型类上,对模型类作注解

@ApiModelProperty 用在属性上,对属性作注解

代码演示:

/*** <pre>*     人员信息类* </pre>**/
@Data
@ApiModel(description= "返回人员信息")
public class UserQueryVo extends BaseEntity{@ApiModelProperty(value = "主键", required = true)@TableId(value = "id", type = IdType.ID_WORKER)private Long id;@ApiModelProperty(value = "手机号", required = true)private String phonenum;@ApiModelProperty(value = "密码", required = true)private String password;@ApiModelProperty(value = "年龄", required = true)private Integer age;
}

7.@PathVariable

@PathVariable用于获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数。

代码示例：

复制代码

 /*** 人员信息*/@GetMapping("/info/{id}")@RequiresPermissions("tour:vehicle:info:info")@ApiOperation(value = "获取user对象详情", notes = "查看人员信息")public ApiResult<UserQueryVo> getTourVehicleInfo(@PathVariable("id") Long id) throws Exception {UserQueryVo userQueryVo= userService.getTourVehicleInfoById(id);return ApiResult.ok(userQueryVo);}

三.注解使用注意点

1.为了在swagger-ui上看到输出,至少需要两个注解:@Api和@ApiOperation
2.即使只有一个@ApiResponse,也需要使用@ApiResponses包住使用
3.对于@ApiImplicitParam的paramType: query,from域中的值需要使用@RequerstParam获取, header域中的只需要使用@RequestHeader来获取,path域中的值需要使用@PathVariable来获取,body域中的值使用@RequestBody来获取,否则可能出错;而且如果paramType是body,name不能是body,否则有问题,与官方文档中的"if paramType is "body",the name should be "body" "不符

swagger常用注解相关推荐

Spring Boot 1.5.8集成Swagger2 + YApi —— Swagger常用注解说明
前言受新型冠状病毒的影响,在家像猪一样不是睡就是吃,闲着就学着用下Swagger和YApi,特将这几天的学习成果写成了这系列的文章,希望能对大家有所帮助.武汉加油,中国加油! Spring Boot ...
springmvc整合swagger 与常用注解说明
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使 ...
swagger注解说明_swagger2常用注解说明
原文:https://blog.csdn.net/u014231523/article/details/76522486 说明: 1.这里使用的版本:springfox-swagger2(2.4)sp ...
Swagger 学习笔记 | Swagger 简介 | Springfox 简介 | Springfox 2.9.2 常用注解 | Spring Boot 整合 Swagger2 案例
文章目录一.Swagger 简介二.Springfox 简介三.Springfox2.9.2 常用注解四.SpringBoot 整合 Swagger2 4.1 引入Maven依赖 4.2 项目 ...
SpringBoot+Swagger2常用注解
场景 SpringBoot+Swagger2实现可视化API文档流程: https://blog.csdn.net/BADAO_LIUMANG_QIZHI/article/details/936166 ...
postmapping注解_Swagger常用注解
在使用swagger时候如果掌握一些注解的使用,则在开发过程中测试的时候可以事半功倍,尤其在与前端技术进行联调,前端技术在访问swagger中的每个api时,可以很清楚的知道每个url对应的请求类型. ...
Swagger2常用注解说明
文章目录 Swagger2简介使用Swagger解决的问题 Spring Boot集成Swagger2 添加依赖添加Swagger2Config配置类编写接口用户DTO 用户controlle ...
常用注解，依赖，常用类，插件和其它（自用）
目录参考下面是自己写的笔记 java注解大全参考: 实用的注解: @Controller 和 @RestController @RequestMapper @PathVariable 和 @Req ...
springboot 集成 Swagger2 配置以及常用注解的说明和使用（超详细）
一.注解的使用和说明结构化说明如下: @Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" (也就是给类取别名) ...
Java常用注解以及使用场景示例
Java注解定义 Java注解是Java编程语言中的一种特殊形式的元数据,它们可以用于为程序的各个元素(例如类.方法.字段等)添加额外的信息和属性.注解是在Java 5中引入的,通过在代码中使用注解, ...

swagger常用注解

一.简介

1.什么是swagger

2.swagger的特征

3.swagger依赖包

二.swagger常用注解

1.@Api

2.@ApiOperation

3.@ApiParam

4.@ApiImplicitParams、@ApiImplicitParam

5.@ApiResponses、@ApiResponse

6.@ApiModel、@ApiModelProperty

7.@PathVariable

三.注解使用注意点

swagger常用注解相关推荐

最新文章

热门文章