current position:Home>Some lessons learned from SWGGER2

Some lessons learned from SWGGER2

2022-09-23 10:21:02Actually I'm real

最近项目要用到swagger,网上查了一下,现在一般都是用swagger2,我对他的理解是一个restfulInterface description and testing framework.Then I found an example from the Internet,But examples are often problematic,After checking the notes, the description is as follows.

The problem with the example is that the user adds the query interface,添加没问题,查询的时候,用swgger-ui的那个界面url是

localhost:8080/users/{id},But put mine when testing{id}as a parameter value,提示类型转换错误,Actually my parameter value is1,But the frame is not recognized,According to the instructions found,我将我的@ApiImplicitParamadded to the tagparamType="path",之后uiThe test page is available.



注解说明:


@Api:用在类上,说明该类的作用

@ApiOperation:用在方法上,说明方法的作用,标注在具体请求上,value和notes的作用差不多,都是对请求进行说明;tags则是对请求进行分类的,比如你有好几个controller,分别属于不同的功能模块,那这里我们就可以使用tags来区分了,看上去很有条理

@ApiImplicitParams:用在方法上包含一组参数说明

@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

paramType:参数放在哪个地方

header-->请求参数的获取:@RequestHeader

query-->请求参数的获取:@RequestParam

path(用于restful接口)-->请求参数的获取:@PathVariable

body(不常用)

form(不常用)

name:参数名

dataType:参数类型

required:参数是否必须传

value:参数的意思

defaultValue:参数的默认值

@ApiResponses:用于表示一组响应

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

code:数字,例如400

message:信息,例如"请求参数没填好"

response:抛出异常的类

@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)表明这是一个被swagger框架管理的model,用于class上

@ApiModelProperty 这里顾名思义,描述一个model的属性,就是标注在被标注了@ApiModel的class的属性上,这里的value是对字段的描述,example是取值例子,注意这里的example很有用,对于前后端开发工程师理解文档起到了关键的作用,因为会在api文档页面上显示出这些取值来;这个注解还有一些字段取值,可以自己研究,举例说一个:position,表明字段在model中的顺序


以上这些就是最常用的几个注解了.


copyright notice
author[Actually I'm real],Please bring the original link to reprint, thank you.
https://en.cdmana.com/2022/266/202209231010448101.html

Random recommended