(转发) swagger注释API详细说明

参考: https://blog.csdn.net/xupeng874395012/article/details/68946676  https://blog.csdn.net/yilishuku/article/details/81197448

  随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。    --引用 RyuGou的专栏

API详细说明

注释汇总

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

@RequestMapping此注解的推荐配置

  value, method,produces

示例:

   @ApiOperation("信息软删除")
    @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"),
            @ApiResponse(code = CommonStatus.EXCEPTION, message = "服务器内部异常"),
            @ApiResponse(code = CommonStatus.FORBIDDEN, message = "权限不足") })
    @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true) })
    @RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public RestfulProtocol remove(Long id) {  }
@ApiModelProperty(value = "标题")
    private String  title;

@ApiImplicitParam

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

paramType 示例详解

path

 @RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

 @PathVariable(name = "id") Long id

body

@ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息参数", required = true) })
  @RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)

  @RequestBody MessageParam param

  提交的参数是这个对象的一个json,然后会自动解析到对应的字段上去,也可以通过流的形式接收当前的请求数据,但是这个和上面的接收方式仅能使用一个(用@RequestBody之后流就会关闭了)

header

 @ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) }) 

   String idstr = request.getHeader("id");
        if (StringUtils.isNumeric(idstr)) {
            id = Long.parseLong(idstr);
        }

Form

@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) })
 @RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATION_J

原文地址:https://www.cnblogs.com/JoeyWong/p/9456382.html

时间: 08-10

(转发) swagger注释API详细说明的相关文章

Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api

本文作者:小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119 实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率. 听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下. 一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,

Core Web API上使用Swagger提供API文档

在ASP.NET Core Web API上使用Swagger提供API文档 我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页面后,在IISExpress启动Web API站点后,会自动重定向到API文档页面,非常方便.这不仅让我能够快速省查API设计的合理性,同时从API的使用角度也为我自己提供了便捷.下图就是我的博客系统RESTful API

用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档

博客搬到了fresky.github.io - Dawei XU,请各位看官挪步.最新的一篇是:用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档.

DNS协议原理、安装及主从同步、负载均衡和转发、缓存的详细配置

DNS(域名系统),用于解析域名和IP地址之间的映射关系 协议使用端口: udp 53     正常查询解析情况下使用udp53 tcp53        当进行主从之间的区域传送时使用tcp53 DNS域的空间划分 DNS的查询方式 递归查询 当主机A要向DNS服务器发送查询主机D的请求时,服务器返回给A最终结果,这种方式就是递归查询,如果客户端要查找的内容直接在服务器上得到结果,刚给出的答案是一个权威答案,否则就是一个参考答案. 迭代查询 NS服务器接收到A的请求后,本地没有D的解析,则会通

7.Configurator API 详细介绍

一.Configurator类介绍与API解释 1.Configurator类介绍 1)用于设置脚本动过的默认延时 2)功能 a.可调节两个模拟动作间的默认时间间隔 b.可调节输入文本的输入时间间隔 c.可调节每次滚动的时间间隔 2.相关API 延时项 默认延时 功能描述 API 动作 3s 设置延时 setActionAckonwledgmentTimeout(long timeout) 获取默认延时 getActionAckonwledgmentTimeout() 键盘输入 0s 设置延时

6.UiWatcher API 详细介绍

Tip: 1.监听器不是完能的,所以若用例需要设置监听器防止用例被打断,最好把延迟时间调高一点 2.UiDevice是不会触发监听功能的 3.监听器在方法体或者循环体中是程序还是会被打断的 4.监听器要在防止中断用例前执行 一.UiWatcher类介绍与中断监听检查条件 1.UiWatcher类说明 1)UiWatcher用于处理脚本执行过程中遇到的非想象的步骤 2)UiWatcher使用场景 测试过程中来了个电话 测试过程中收到个短信 测试过程中闹钟响了 …… 2.中断监听检查条件 API:

1.UiDevice API 详细介绍

1.UiDevice按键与keycode使用 返回值 方法名 说明 boolean pressBack() 模拟短按返回back键 boolean pressDPadCenter() 模拟按轨迹球中点按键 boolean pressSPadDown() 模拟轨迹球向下按键 boolean pressDPadLeft() 模拟轨迹球向左按键 boolean pressDPadRight() 模拟轨迹球向右按键 boolean pressDPadUp() 模拟轨迹球向上按键 boolean pres

vector API详细学习

vector是一种顺序容器. 构造函数: vector(); vector( const vector& c ); vector( size_type num, const TYPE& val = TYPE() ); vector( input_iterator start, input_iterator end ); 例子: #include <iostream> #include <vector> using namespace std; int main()

利用Swagger Maven Plugin生成Rest API文档

利用Swagger Maven Plugin生成Rest API文档 Swagger Maven Plugin This plugin enables your Swagger-annotated project to generate Swagger specs and customizable, templated static documents during the maven build phase. Unlike swagger-core, swagger-maven-plugin

Swagger框架学习分享

Swagger框架学习分享 转至元数据结尾 Created and last modified by 刘新宇 大约1分钟以前 转至元数据起始 一.背景介绍 1.1.项目简介 1.2.code repository 1.3.演示项目 二.开发准备 2.1.环境准备 2.2.项目搭建 2.2.1.jar仓库 2.2.2.相关依赖 2.2.3.编写配置文件 2.2.4.与swagger-ui集成 2.6.5.Controller配置 2.2.6.启动中间件 2.2.7.需求定制 三.学习感想 一.背景