首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >Swagger规范 之 出错点

Swagger规范 之 出错点

作者头像
贺贺V5
发布2019-10-10 14:45:17
4070
发布2019-10-10 14:45:17
举报

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

本文参与 腾讯云自媒体分享计划,分享自作者个人站点/博客。
原始发表:2019.10.09 ,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 出错点
    • 写路径时的出错
    相关产品与服务
    Serverless HTTP 服务
    Serverless HTTP 服务基于腾讯云 API 网关 和 Web Cloud Function(以下简称“Web Function”)建站云函数(云函数的一种类型)的产品能力,可以支持各种类型的 HTTP 服务开发,实现了 Serverless 与 Web 服务最优雅的结合。用户可以快速构建 Web 原生框架,把本地的 Express、Koa、Nextjs、Nuxtjs 等框架项目快速迁移到云端,同时也支持 Wordpress、Discuz Q 等现有应用模版一键快速创建。
    领券
    问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档