swagger 返回值描述

今天被前端训了一顿,慌得一逼,说你们写的接口,返回值写的是什么东西,只有公共的三个字段......

我们的API文档是基于 swagger 组件写的.如是有了下面的东东

 

示例:

image.png

 

1.1.           返回字段

1.1.1.  返回字段(对象)

1.     将现有接口 @ApiOperation 注解,response字段去掉.

该字段作用:声明指定返回值对象

image.png

 

修改后:

image.png

 

2.     将返回对象进行泛型声明

声明后swagger(丝袜哥) 会反射生成对象字段描述

 image.png

3.     使用 @ApiModelPropety 注解写明字段含义

@ApiModelProperty("XXX")

 

示例:

 

 image.png

1.1.2.  返回字段(单字段)

对于单字段及5个字段以内,可以用此方式说明返回值

 

image.png

 

 

1.2.      请求字段

1.2.1.  请求字段(对象)

接口入参声明为对象接收

 

 image.png

对象字段用 @ApiParam 注解进行标注

 

 image.png

1.2.2.  请求字段(单字段或多字段)

单字段或多字段用 @ApiImplicitParams @ApiImplicitParam 进行标注

image.png

转自:https://blog.51cto.com/5634409/2343942

  • 1
    点赞
  • 5
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
接口文档 Swagger(原名Swagger Specification,现简称 OpenAPI)是一个用于编写、描述和交换 RESTful Web 服务契约的规范和工具集。它供了一种标准化的方式来定义 API 的结构、参数、返回值以及可能的状态码等信息,使得开发者能够更容易地理解和消费 API。 Swagger 完整的接口文档通常包括以下几个部分: 1. **API 描述**:文档的开头会有一段关于 API 的总体概述,包括用途、版本、作者等信息。 2. **资源(Resources)**:定义了 API 中的不同端点或操作,每个资源都有其路径、方法(GET, POST, PUT, DELETE 等)、请求参数等详细说明。 3. **数据模型(Data Models)**:定义 API 中使用的各种数据类型,如对象、数组等,并供了字段的名称、类型、默认值等。 4. **参数(Parameters)**:列举了 HTTP 请求中的所有参数,包括路径参数、查询参数、请求头、请求体等及其约束条件。 5. **响应(Responses)**:定义了 API 各个端点可能返回的各种状态码对应的响应格式和内容。 6. **示例(Examples)**:为开发者展示如何正确调用 API 并展示了预期的输入输出样例。 7. **安全性(Security Definitions)**:如果 API 需要身份验证,这里会列出所支持的认证机制和相应的令牌格式。 Swagger 供了在线工具和 SDK,使得生成 API 文档变得简单,同时也方便了客户端的自动生成,如代码生成器能根据 Swagger 文档快速生成客户端库。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值