转载

TP5集成Swagger编写API文档（二）

YAML语法

继续上篇内容

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

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

这种语法叫做 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

正文到此结束

所属分类：软件架构编程技术

本文标签： Security 协议 description SDN 开发 Authorization apache find API 参数博客数据 key 删除 js 开发者 json http tag https UI HTML 主机模型 ip 配置需求 src IO mail 标题 schema Service node 功夫代码
版权声明： 本文为互联网转载文章，出处已在文章中说明(部分除外)。如果侵权，请联系本站长删除，谢谢。
本文海报： 生成海报一生成海报二

其他链接

关于本站

本站定位：个人技术类博客

本站作用：写博客、记日志、闲聊扯淡鼓捣技术。

问题交流

TP5集成Swagger编写API文档（二）

YAML语法

参数意义

热门推荐

相关文章

说给你听

本文目录

随机标签

书籍教程

近期评论

网站信息

其他链接

关于本站

问题交流