写在前面
今天我们来学习Swagger中的一些常用注解,虽然我们可能常用的注解就那么几个,但是如果要像外部展示更多信息的话,还是非常 有必要学习的。
Swagger常用的注解如何使用?
Swagger是生成api文档的一个组件,本篇文章不是讲如何集成,而是讲述一下其中的一些注解的使用。
来看一下吧。
@Api注解
此注解,是用于修饰类名的,其中可以传入value参数,和tags参数等等。
value参数是用于体现此类接口的大标题。
而tags参数是用来展示此类接口的一些关键说明。
@ApiModel注解
此注解,是用于修饰数据模型,同样也是修饰类名的。
一般都是修饰数据模型相关的类,其中也可以传入value,用于数据模型的命名。
除了value外,还有description参数,从名称来看就知道是描述的作用。
在数据模型中其实也可以不传入value,但是如果一个项目内有两个都没有传入,swagger中就会只有一个数据模型,因为没有vlaue名称,没办法起到唯一标识的作用;就只能覆盖了。
@ApiModelProperty注解
此注解,和APIModel是搭配使用的,如果数据模型被ApiModel修饰了,那么其中的变量也要输出到swagger文档中呀。
所以就用得上ApiModelProperty注解了,来修饰变量,并且可以指定value,来对变量进行一个说明。
这个注解是用的最多的了,其中还有name,也就是重写该变量的名称。
dataType属性,从名称来看就知道是数据类型,指定的也是该变量的数据类型。
还有required属性,标识该字段是否必填。
hidden属性,就是隐藏了,这个不用多说。
总结
今天我们来学习了swagger中的一些注解,如果你使用过,其实也没什么,根据自己的文档展示需要妥善使用注解即可。