继续上篇内容
swagger editor 中左侧有大量的数据,有一些基本的属性我们要学习,所以学习swagger 是有一定成本的
先不管这些数据代表什么意思,我们首先看一下左侧的语法结构,摘要一部分如下
这种语法叫做 YAML,详细的介绍可以参见如下博客
YAML语法
这里只介绍基本语法规则
其值可以是字符串、对象、数组、引用等类型
有的同学问,可以使用json格式编写吗?当然可以,但是显然对于配置文件来说,YAML语法要比json简单很多,所以这里可以花费点功夫学习YAML语法
理解了YAML语法结构后,就要了解左侧的参数到底都是什么意思,可以从头梳理
左侧其实就是Open API Spec,也就是编写的是OPEN API 的规范,也就是说我们按照这个规范来编写Open 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"
这两个数据组合到一起就是api的公共路径信息,如做出如下更改
host: "smple.cn" basePath: "/v1"
最终所有api的请求路径都是 simple.cn/v1,修改之后,发现右侧的实时预览也发生了变化
可以这样理解,比如我们提供了电影、音乐、图书三组api,tags属性就可以设置 movies music 和 book 三个值,这样有利于将所有api分组展示,以获取更加良好的展示
修改如下
tags: - name: "book" description: "图书相关api" - name: "music" description: "音乐相关api" - name: "movies" description: "电影相关api"
另外,如果api非常简单,没有这么多分组,也可以删除 tags 属性
注意,此项的值是一个数组,元素的顺序决定了api优先使用的协议
schemes: - "http" - "https"
示例描述了路径的写法,路径的写法要遵循api的命名规范
具体的api明明规范,单独一篇博客说明
HTTP 方法最常用的就是 post、get、put和delete
以/pet 为例,展开代码,其中参数的意义如下所示
大家注意,其中有几个参数我们有添加注解
另外,注意parameters 中的 schema 参数的值是
$ref: "#/definitions/Pet"
表示引用了definitions 中的 pet引用(引用也是YAML语法特性之一)
这里为什么使用引用?因为post 是新增一条数据,那么就需要向api提供一个对象,对象中的键值对可能很多,所以先在后面定义了一个Pet模型,然后再这里引用即可,有人说为什么不再这里定义,因为其他地方也需要引用这个模型
多说无益,下面根据自己的需求更改这个数据。途中标识出的是修改的地方
然后再定义一个Book模型
找到与 paths 同级别的 definitions,里面已经定义了几个模型
我们仿照其他模型的语法定义Book模型
到这里,一个api就配置好了
按照同样的方式配置其他api即可