发布：2022/3/10 16:05:54作者：管理员 来源：本站 浏览次数：1198

上一章讲述了Springboot+Idea+JDK8配置一个简单的Swagger访问页面,

接下来,详细解释一下Swagger中配置的常用的api
注解    功能

@Api   
    作用于类,描述类,不用不扫描
@ApiOperation    作用于方法,描述方法
@ApiParam    作用于参数,描述参数
@ApiImplicitParam 和 @ApiImplicitParams     作用于参数,描述参数
@ApiModel     作用于类,描述实体类
@ApiModelProperty    作用于字段,描述字段属性
1、@Api

  用在类上,说明这个类的作用,如果类不配置,则swagger默认不扫描该类,如上图中的展示

@Api(tags = "SwaggerTest", description = "swagger展示的接口调用")

其中的属性:常用为加粗
属性名称     备注
value    url的路径值
tags    API分组标签。具有相同标签的API将会被归并在一组内展示,如果设置这个值、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 将在文档中隐藏
 
 
2、@ApiOperation

  用在方法上,说明方法的作用,一般搭配@GetMapping 、 @PostMapping 、 @PutMapping 、@DeleteMapping  通过不同的http method 区分使用

    GET（SELECT）：从服务器查询资源（一项或多项）

    POST（CREATE）：在服务器新建一个资源

    PUT（UPDATE）：在服务器更新一个资源【较少使用】

    DELETE（DELETE）：从服务器删除资源【较少使用】

    @GetMapping("getTest")
    @ApiOperation(value = "获取信息")

其中的属性:常用为加粗
属性名称    备注
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",新版本不用单独配置,使用@GetMapping可自动扫描出来
code    http的状态码 默认 200
extensions    扩展属性
 
 
3、@ApiParam标记

  增加对参数的说明

        @GetMapping("getTest")
        @ApiOperation(value = "获取信息")
        public String getTest(
                @ApiParam(name = "target", value = "target", required = true) @RequestParam("target")
                        String target) {
            
            return "信息" + target;
        }

其中的属性:常用为加粗
属性名称    备注
name    属性名称
value    属性值
defaultValue    默认属性值
allowableValues    可以不配置
required    是否属性必填
access    不过多描述
allowMultiple    默认为false
hidden    隐藏该属性
example    举例
 
3-1@ApiImplicitParam 和 @ApiImplicitParams

同样使用在参数的的还有另一个注解@ApiImplicitParam   和 @ApiImplicitParams  使用方法同下,具体使用那个看使用习惯了,如果只有一个参数只需要配置@ApiImplicitParam就可以了

        @PostMapping("postTest")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "username", value = "账号", dataType = "String", paramType = "query"),
                @ApiImplicitParam(name = "password", value = "密码", dataType = "String", paramType = "query"),
                @ApiImplicitParam(name = "type", value = "类型", dataType = "String", paramType = "query")
        })
        @ApiOperation(value = "新增信息")
        public String postTest(String username, String password, String type) {
            return "新增信息" + username + password + type;
        }

其中的属性:常用为加粗
属性名称    备注
name    参数名
value    参数的汉字说明,解释
required    是否属性必填
paramType    

参数放在哪个地方，查询参数类型，这里有几种形式：

    header --> 请求参数的获取：@RequestHeader，参数在request headers 里边提交

    query --> 请求参数的获取：@RequestParam，直接跟参数，完成自动映射赋值

    path（用于restful接口）--> 请求参数的获取：@PathVariable，以地址的形式提交数据

    body（不常用）--> 以流的形式提交 仅支持POST

    form（不常用）--> 以form表单的形式提交 仅支持POST

dataType    参数类型，默认String，其它值dataType="Integer"
defaultValue    参数的默认值
 
 
4、@ApiModel 和 @ApiModelProperty

  描述一个实体类的信息,一般接参或者给前端返回是实体类对象时候,在实体类对象上加的注解

    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
     
    @Data//lombok注解，代替get和set方法
    @ApiModel(value = "Person", description = "人员实体类")
    public class Person {
     
        @ApiModelProperty(value = "id", required = false, example = "1")
        private Integer id;
     
        @ApiModelProperty(value = "用户名", required = true, example = "张三")
        private String userName;
     
        @ApiModelProperty(value = "密码", required = true, example = "123456")
        private String passWord;
     
    }

 

@ApiModel 对应属性
属性名称    数据类型    默认值    说明
value    String    类名    为模型提供备用名称
description    String    “”    提供详细的类描述
parent    Class<?> parent    Void.class    为模型提供父类以允许描述继承关系
discriminatory    String    “”    支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
subTypes    Class<?>[]    {}    从此模型继承的子类型数组
reference    String    “”    指定对应类型定义的引用，覆盖指定的任何其他元数据

 

@ApiModelProperty对应属性
属性名称    数据类型    默认值    说明
value    String    “”    属性简要说明
name    String    “”    运行覆盖属性的名称。重写属性名称
allowableValues    String    “”    限制参数可接收的值，三种方法，固定取值，固定范围
access    String    “”    过滤属性，参阅:io.swagger.core.filter.SwaggerSpecFilter
notes    String    “”    
dataType    String    “”    参数的数据类型，可以是类名或原始数据类型，此值将覆盖从类属性读取的数据类型
required    boolean    false    是否为必传参数,false:非必传参数; true:必传参数
position    int    0    允许在模型中显示排序属性
hidden    boolean    false    隐藏模型属性，false:不隐藏; true:隐藏
example    String    “”    属性的示例值
readOnly    boolean    false    指定模型属性为只读，false:非只读; true:只读
reference    String    “”    指定对应类型定义的引用，覆盖指定的任何其他元数据
allowEmptyValue    boolean    false    允许传空值，false:不允许传空值; true:允许传空值

个人而言一般就是用这么多,因为返回值不配置Swagger也是会自动扫描的,如果返回是对象,有@ApiModel也就可以了

但是为了可能用到的同学到处找不到,功能如下
@ApiResponses 和 @ApiResponse

配置返回信息,作用于方法上

        @PutMapping("postTest2")
        @ApiResponses({@ApiResponse(code = 200, message = "成功")
                , @ApiResponse(code = 400, message = "失败")})
        @ApiOperation(value = "新增信息")
        public String postTest2() {
            return "测试返回值";
        }

@ApiResponse 对应属性    @ApiResponses 的属性就是多个@ApiResponse
属性名称    备注
code    http的状态码
message    描述
response    默认响应类 Void
reference    参考ApiOperation中配置
responseHeaders    参考 ResponseHeader 属性配置说明
responseContainer    参考ApiOperation中配置
@ResponseHeader

响应头设置，使用方法

@ResponseHeader(name="head1",description="response head conf")

属性名称    备注
name    响应头名称
description    头描述
response    默认响应类 Void
responseContainer    参考ApiOperation中配置

 

本文大量抄袭+整合,所用到的博文地址如下,如不能抄袭,保证立刻删除整改:

https://www.jianshu.com/p/12f4394462d5

https://juejin.cn/post/6844903901724950535

https://blog.csdn.net/dejunyang/article/details/89527348