转载

TP5集成Swagger编写API文档(二)

YAML语法

继续上篇内容

swagger editor 中左侧有大量的数据,有一些基本的属性我们要学习,所以学习swagger 是有一定成本的

先不管这些数据代表什么意思,我们首先看一下左侧的语法结构,摘要一部分如下

TP5集成Swagger编写API文档(二)

这种语法叫做 YAML,详细的介绍可以参见如下博客

YAML语法

这里只介绍基本语法规则

TP5集成Swagger编写API文档(二)

其值可以是字符串、对象、数组、引用等类型

有的同学问,可以使用json格式编写吗?当然可以,但是显然对于配置文件来说,YAML语法要比json简单很多,所以这里可以花费点功夫学习YAML语法

参数意义

理解了YAML语法结构后,就要了解左侧的参数到底都是什么意思,可以从头梳理

左侧其实就是Open API Spec,也就是编写的是OPEN API 的规范,也就是说我们按照这个规范来编写Open API

  • swagger:描述swagger 的版本信息
  • info:提供API的元数据,如API标题、介绍、开发者联系方式、版本信息等,这里的信息可以根据情况自行更改,也可以删除一些不需要的属性
swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

下面是更改之后的数据结构

swagger: "2.0"
info:
  description: "本文档提供孤岛小程序所有API的说明"
  version: "1.0.0"
  title: "孤岛小程序API"
  termsOfService: "http://simple.cn/terms/"
  contact:
    email: "onlifes@yeah.net"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
  • host:主机地址
  • basePath:相对于host的根路径

这两个数据组合到一起就是api的公共路径信息,如做出如下更改

host: "smple.cn"
basePath: "/v1"

最终所有api的请求路径都是 simple.cn/v1,修改之后,发现右侧的实时预览也发生了变化

TP5集成Swagger编写API文档(二)

  • tags:补充的元数据,在swagger ui中,用于作为api的分组标签

可以这样理解,比如我们提供了电影、音乐、图书三组api,tags属性就可以设置 movies  music 和 book 三个值,这样有利于将所有api分组展示,以获取更加良好的展示

修改如下

tags:
- name: "book"
  description: "图书相关api"
- name: "music"
  description: "音乐相关api"
- name: "movies"
  description: "电影相关api"

TP5集成Swagger编写API文档(二)

另外,如果api非常简单,没有这么多分组,也可以删除 tags 属性

  • schemes,API的传输协议,http,https,ws,wss

注意,此项的值是一个数组,元素的顺序决定了api优先使用的协议

schemes:
- "http"
- "https"
  • paths:API的路径,以及每个路径的HTTP方法,一个路径加上一个HTTP方法构成了一个操作

示例描述了路径的写法,路径的写法要遵循api的命名规范

TP5集成Swagger编写API文档(二)

具体的api明明规范,单独一篇博客说明

HTTP 方法最常用的就是 post、get、put和delete

以/pet 为例,展开代码,其中参数的意义如下所示

TP5集成Swagger编写API文档(二)

大家注意,其中有几个参数我们有添加注解

  • consumes:规定向api发起请求时的MIME类型,只有符合这个类型api才会受理
  • produces:规定api返回响应时的MIME类型
  • security:验证,比较复杂,单独再说

另外,注意parameters 中的 schema 参数的值是

$ref: "#/definitions/Pet"

表示引用了definitions 中的 pet引用(引用也是YAML语法特性之一)

这里为什么使用引用?因为post 是新增一条数据,那么就需要向api提供一个对象,对象中的键值对可能很多,所以先在后面定义了一个Pet模型,然后再这里引用即可,有人说为什么不再这里定义,因为其他地方也需要引用这个模型

多说无益,下面根据自己的需求更改这个数据。途中标识出的是修改的地方

TP5集成Swagger编写API文档(二)

然后再定义一个Book模型

找到与 paths 同级别的 definitions,里面已经定义了几个模型

TP5集成Swagger编写API文档(二)

我们仿照其他模型的语法定义Book模型

TP5集成Swagger编写API文档(二)

到这里,一个api就配置好了

TP5集成Swagger编写API文档(二)

按照同样的方式配置其他api即可

原文  https://blog.csdn.net/mynewdays/article/details/89065114
正文到此结束
Loading...