TP5集成Swagger编写API文档（二）
YAML语法
继续上篇内容
swagger editor 中左侧有大量的数据，有一些基本的属性我们要学习，所以学习swagger 是有一定成本的
先不管这些数据代表什么意思，我们首先看一下左侧的语法结构，摘要一部分如下
这种语法叫做 YAML，详细的介绍可以参见如下博客
YAML语法
这里只介绍基本语法规则
其值可以是字符串、对象、数组、引用等类型
有的同学问，可以使用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，修改之后，发现右侧的实时预览也发生了变化
- tags：补充的元数据，在swagger ui中，用于作为api的分组标签
可以这样理解，比如我们提供了电影、音乐、图书三组api，tags属性就可以设置 movies music 和 book 三个值，这样有利于将所有api分组展示，以获取更加良好的展示
修改如下
tags: - name: "book" description: "图书相关api" - name: "music" description: "音乐相关api" - name: "movies" description: "电影相关api"
另外，如果api非常简单，没有这么多分组，也可以删除 tags 属性
- schemes，API的传输协议，http，https，ws，wss
注意，此项的值是一个数组，元素的顺序决定了api优先使用的协议
schemes: - "http" - "https"
- paths：API的路径，以及每个路径的HTTP方法，一个路径加上一个HTTP方法构成了一个操作
示例描述了路径的写法，路径的写法要遵循api的命名规范
具体的api明明规范，单独一篇博客说明
HTTP 方法最常用的就是 post、get、put和delete
以/pet 为例，展开代码，其中参数的意义如下所示
大家注意，其中有几个参数我们有添加注解
- consumes：规定向api发起请求时的MIME类型，只有符合这个类型api才会受理
- produces：规定api返回响应时的MIME类型
- security：验证，比较复杂，单独再说
另外，注意parameters 中的 schema 参数的值是
$ref: "#/definitions/Pet"
表示引用了definitions 中的 pet引用（引用也是YAML语法特性之一）
这里为什么使用引用？因为post 是新增一条数据，那么就需要向api提供一个对象，对象中的键值对可能很多，所以先在后面定义了一个Pet模型，然后再这里引用即可，有人说为什么不再这里定义，因为其他地方也需要引用这个模型
多说无益，下面根据自己的需求更改这个数据。途中标识出的是修改的地方
然后再定义一个Book模型
找到与 paths 同级别的 definitions，里面已经定义了几个模型
我们仿照其他模型的语法定义Book模型
到这里，一个api就配置好了
按照同样的方式配置其他api即可
正文到此结束
热门推荐
相关文章
Loading...
![[HBLOG]公众号](http://www.liuhaihua.cn/img/qrcode_gzh.jpg)
