码迷,mobileinhere.cn
首页 > windows程序 > 详细

swagger注释api详细说明

时间:2018-03-07 11:45:43      阅读:2475      评论:0      收藏:0      [点我收藏+]

标签:reference   path   ons   基本   状态   .class   param   options   except   

常用到的注解有:
  • api
  • apimodel
  • apimodelproperty
  • apioperation
  • apiparam
  • apiresponse
  • apiresponses
  • responseheader
1. api标记

api 用在类上,说明该类的作用。可以标记一个controller类做为swagger 文档资源,使用方式:

@api(value = "/user", description = "operations about user")

与controller注解并列使用。 属性配置:

属性名称备注
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 将在文档中隐藏

在springmvc中的配置如下:

@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:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:

@apioperation(
          value = "find purchase order by id",
          notes = "for valid response try integer ids with value <= 5 or > 10. other values will generated exceptions",
          response = order,
          tags = {"pet store"})

与controller中的方法并列使用。
属性配置:

属性名称备注
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 扩展属性

在springmvc中的配置如下:

@requestmapping(value = "/order/{orderid}", method = get)
  @apioperation(
      value = "find purchase order by id",
      notes = "for valid response try integer ids with value <= 5 or > 10. other values will generated exceptions",
      response = order.class,
      tags = { "pet store" })
   public responseentity<order> 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. apiparam标记

apiparam请求属性,使用方式:

public responseentity<user> createuser(@requestbody @apiparam(value = "created user object", required = true)  user user)

与controller中的方法并列使用。

属性配置:

属性名称备注
name 属性名称
value 属性值
defaultvalue 默认属性值
allowablevalues 可以不配置
required 是否属性必填
access 不过多描述
allowmultiple 默认为false
hidden 隐藏该属性
example 举例子

在springmvc中的配置如下:

 public responseentity<order> getorderbyid(
      @apiparam(value = "id of pet that needs to be fetched", allowablevalues = "range[1,5]", required = true)
      @pathvariable("orderid") string orderid)
4. apiresponse

apiresponse:响应配置,使用方式:

@apiresponse(code = 400, message = "invalid user supplied")

与controller中的方法并列使用。 属性配置:

属性名称备注
code http的状态码
message 描述
response 默认响应类 void
reference 参考apioperation中配置
responseheaders 参考 responseheader 属性配置说明
responsecontainer 参考apioperation中配置

在springmvc中的配置如下:

 @requestmapping(value = "/order", method = post)
  @apioperation(value = "place an order for a pet", response = order.class)
  @apiresponses({ @apiresponse(code = 400, message = "invalid order") })
  public responseentity<string> placeorder(
      @apiparam(value = "order placed for purchasing the pet", required = true) order order) {
    storedata.add(order);
    return ok("");
  }
5. apiresponses

apiresponses:响应集配置,使用方式:

 @apiresponses({ @apiresponse(code = 400, message = "invalid order") })

与controller中的方法并列使用。 属性配置:

属性名称备注
value 多个apiresponse配置

在springmvc中的配置如下:

 @requestmapping(value = "/order", method = post)
  @apioperation(value = "place an order for a pet", response = order.class)
  @apiresponses({ @apiresponse(code = 400, message = "invalid order") })
  public responseentity<string> placeorder(
      @apiparam(value = "order placed for purchasing the pet", required = true) order order) {
    storedata.add(order);
    return ok("");
  }
6. responseheader

响应头设置,使用方法

@responseheader(name="head1",description="response head conf")

与controller中的方法并列使用。 属性配置:

属性名称备注
name 响应头名称
description 头描述
response 默认响应类 void
responsecontainer 参考apioperation中配置

在springmvc中的配置如下:

@apimodel(description = "群组")
7. 其他
  • @apiimplicitparams:用在方法上包含一组参数说明;
  • @apiimplicitparam:用在@apiimplicitparams注解中,指定一个请求参数的各个方面
    • paramtype:参数放在哪个地方
    • name:参数代表的含义
    • value:参数名称
    • datatype: 参数类型,有string/int,无用
    • required : 是否必要
    • defaultvalue:参数的默认值
  • @apiresponses:用于表示一组响应;
  • @apiresponse:用在@apiresponses中,一般用于表达一个错误的响应信息;
    • code: 响应码(int型),可自定义
    • message:状态码对应的响应信息
  • @apimodel:描述一个model的信息(这种一般用在post创建的时候,使用@requestbody这样的场景,请求参数无法使用@apiimplicitparam注解进行描述的时候;
  • @apimodelproperty:描述一个model的属性。


作者:xiangdong_she
链接:www.jianshu.com/p/12f4394462d5
來源:简书
著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。

swagger注释api详细说明

标签:reference   path   ons   基本   状态   .class   param   options   except   

原文地址:www.cnblogs.com/hyl8218/p/8520994.html

(1)
(1)
   
举报
评论 一句话评论(0
0条  
登录后才能评论!
2014 mobileinhere.cn 版权所有 京icp备13008772号-2
华人娱乐注册