Swagger规范 之 出错点

Swagger规范是描述RESTful API的强大的定义格式。Swagger规范创建了一个RESTful接口，通过有效地映射所有资源和与之相关的操作来轻松开发和使用API​​。它易于学习，语言不可知，人类和机器可读。

第一天使用的时候我就发现了它确实易懂，直接写就OK。但是在编写API文档的时候，还是遇到了几个不大不小的坑，记录下来，分享一下，其实是深怕自己过几天就忘了！O(∩_∩)O~

出错点

写路径时的出错

错误事例：

  /login?username={userName}&password={password}:
    $ref: login-inner/login.yaml

url

出错点：
是因为参数配置类型时，写错了，应该是:

parameters:
    - name: devBindingId
      description: 需要审批的记录id
      required: true
      in: path // 不应该是query,而是path
      type: string

备注：
in的不同类型：

• query

/device/binding

http://192.168.90.107:7500/mobileoa/device/binding?devBindingId=1234567

• path

/device/binding/{devBindingId}

http://192.168.90.107:7500/mobileoa/device/binding/123

• body

post请求时，参数放在body中。

parameters:
    - name: 登录参数
      type: json
      in: body
      description: body中的请求参数
      required: true
      prproperties:
        - name: userName
          description: 登录人账号
          required: true
          type: string
        - name: password
          description: 登录人密码
          required: true
          type: string

QQ20170310-175249@2x.png

发出的请求中：

QQ20170310-175500@2x.png

响应体

参考