Swagger Springboot Idea Swagger的API详解(二)

上一章:Swagger Springboot Idea 基础配置(一)

上一章讲述了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.youkuaiyun.com/dejunyang/article/details/89527348