Swagger的Api使用规范

最新推荐文章于 2025-09-20 09:02:42 发布

原创最新推荐文章于 2025-09-20 09:02:42 发布 · 2.4k 阅读

6 ·

CC 4.0 BY-SA版权

文章标签：

#swagger2 #api

博客记录了Swagger2 API的使用规范，上篇仅介绍springboot集成Swagger2，未详述API使用。此次着重讲解了@ApiImplicitParam()内部参数，还提及多参数使用方式，并给出了使用示例。

官网：https://swagger.io/

上篇只是介绍了springboot如何继承swagger2，并没有详细的解释其api的使用，以下记录下使用规范

API使用：

swagger的api
作用范围	API	使用位置
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
描述返回对象的意义	@ApiModel	用在返回对象类上
对象属性	@ApiModelProperty	用在出入参数对象的字段上

@ApiImplicitParam() 内部参数：

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

多参数使用：@ApiImplicitParams（{ @@ApiImplicitParam（），@ApiImplicitParam（），... }）

给出几个使用示例：

    @ApiOperation("添加广告")
    @ApiImplicitParams(@ApiImplicitParam(name = "haicheAd", value = "广告实体", required = true, paramType = "body", dataType = "HaicheAd"))
    @PostMapping(value = "/add")
    public void add(@RequestBody HaicheAd haicheAd) {
        //HaicheAd 对象实体
}


    @ApiOperation("查询广告列表页")
    @ApiImplicitParams({
            @ApiImplicitParam(name="index",value = "广告位置",paramType = "query",dataType = "String"),
            @ApiImplicitParam(name="name",value = "广告名称",paramType = "query",dataType = "String"),
            @ApiImplicitParam(name="del",value = "是否删除 1存在 0删除",paramType = "query",dataType = "int"),
            @ApiImplicitParam(name="page",value = "页码",paramType = "query",dataType = "Integer"),
            @ApiImplicitParam(name="pageSize",value = "页数",paramType = "query",dataType = "int")
    })
    @PostMapping(value = "/listBy")
    public JsonFormat listBy(
            @RequestParam(value = "index",required = false) String index,
            @RequestParam(value = "name",required = false) String name,
            @RequestParam(value = "del",required = false,defaultValue = "1") Integer del,
            @RequestParam(value = "page",defaultValue = "1") Integer page,
            @RequestParam(value = "pageSize",defaultValue = "10") Integer pageSize){

}

@ApiOperation("获取广告详情")
    @ApiImplicitParams(
            @ApiImplicitParam(name="id",value = "广告id",paramType = "path",required = true,dataType = "int"))
    @GetMapping(value = "adInfo/{id}")
    public JsonFormat getAdInfo(@PathVariable(value = "id") Integer id){
}