Swagger常用注解 | 您所在的位置:网站首页 › @schema注解 › Swagger常用注解 |
@ 目录1、@Api2、@ApiOperation3、@ApiOperation3、@ApiImplicitParams、@ApiImplicitParam4、@ApiResponses、@ApiResponse5、@ApiModel、@ApiModelProperty6、 @PathVariable7、 @RequestParamSwagger是一个开放源代码软件框架,由大型工具生态系统支持,可帮助开发人员设计,构建,记录和使用RESTful Web服务。尽管大多数用户通过Swagger UI工具识别Swagger,但是Swagger工具集包括对自动文档,代码生成和测试用例生成的支持。 1、@Api@Api 注解用于标注一个Controller(Class)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。 主要属性如下: 属性 描述 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 将在文档中隐藏实例: @Controller @RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE}) @Api(value = "/pet", description = "Operations about pets") public class PetController { } 2、@ApiOperation@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。 主要属性: 属性 描述 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" code http的状态码 默认 200 extensions 扩展属性实例: @RequestMapping(value = "/order/{orderId}", method = GET) @ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value 10. Other values will generated exceptions", response = Order.class, tags = { "Pet Store" }) public ResponseEntity getOrderById(@PathVariable("orderId") String orderId) throws NotFoundException { Order order = storeData.get(Long.valueOf(orderId)); if (null != order) { return ok(order); } else { throw new NotFoundException(404, "Order not found"); } } 3、@ApiOperation@ApiParam作用于请求方法上,定义api参数的注解。 主要属性: 属性 描述 name 属性名称 value 属性值 defaultValue 默认属性值 allowableValues 可以不配置 required 是否属性必填 access 不过多描述 allowMultiple 默认为false hidden 隐藏该属性 example 举例子实例: public ResponseEntity getOrderById( @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true) @PathVariable("orderId") String orderId) 3、@ApiImplicitParams、@ApiImplicitParam @ApiImplicitParams、@ApiImplicitParam也可以定义参数. @ApiImplicitParams:用在请求的方法上,包含一组参数说明 @ApiImplicitParam:对单个参数的说明主要属性: 属性 描述 name 参数名 value 参数的说明、描述 required 参数是否必须必填 paramType 参数放在哪个地方 query --> 请求参数的获取:@RequestParam header --> 请求参数的获取:@RequestHeader path(用于restful接口)--> 请求参数的获取:@PathVariable body(请求体)--> @RequestBody User user form(普通表单提交) dataType 参数类型,默认String,其它值dataType="Integer" defaultValue 参数的默认值实例: @ApiImplicitParams({ @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"), @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"), @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer") }) @PostMapping("/login") public JsonResult login(@RequestParam String mobile, @RequestParam String password, @RequestParam Integer age){ //... return JsonResult.ok(map); } 4、@ApiResponses、@ApiResponse@ApiResponses、@ApiResponse进行方法返回对象的说明。 主要属性: 属性 描述 code 数字,例如400 message 信息,例如"请求参数没填好" response 抛出异常的类实例: @ApiResponses({ @ApiResponse(code = 200, message = "请求成功"), @ApiResponse(code = 400, message = "请求参数没填好"), @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对") }) @ResponseBody @RequestMapping("/list") public JsonResult list(@RequestParam String userId) { ... return JsonResult.ok().put("page", pageUtil); } 5、@ApiModel、@ApiModelProperty@ApiModel用于描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)。 @ApiModelProperty用来描述一个Model的属性。 实例: @ApiModel(description= "返回响应数据") public class RestMessage implements Serializable{ @ApiModelProperty(value = "是否成功",required=true) private boolean success=true; @ApiModelProperty(value = "错误码") private Integer errCode; @ApiModelProperty(value = "提示信息") private String message; @ApiModelProperty(value = "数据") private Object data; /* getter/setter 略*/ } 6、 @PathVariable@PathVariable用于获取get请求url路径上的参数,即参数绑定的作用,通俗的说是url中"?"前面绑定的参数。 实例: @GetMapping("/query/{id}") private List queryById( @ApiParam(name = "id", value = "学生id", required = true) @PathVariable("id") Long id) { List studentList = studentService.queryById(id); return studentList; } 7、 @RequestParam@RequestParam用于获取前端传过来的参数,可以是get、post请求,通俗的说是url中"?"后面拼接的每个参数。 实例: @GetMapping("/query/student") private List queryByIdStu( @ApiParam(name = "byId", value = "学生id", required = false) @RequestParam("id") Long id) { List studentList = studentService.queryById(id); return studentList; }参考: 【1】:维基百科:Swagger 【2】:不訉biu:Swagger常用注解 【3】:Ido:swagger常用注解说明 【4】:杨梅泡酒:Swagger Annotation 详解(建议收藏) 【5】:xiaojin21cen :swagger2 注解说明 【6】:swagger-core wiki:Swagger 2.X Annotations |
CopyRight 2018-2019 实验室设备网 版权所有 |