API的描述语言--Swagger
作者:互联网
Swagger是一种Rest API的表示方式。
有时也可以作为Rest API的交互式文档,描述形式化的接口描述,生成客户端和服务端的代码。
一,描述语言:Spec
Swagger API Spec是Swagger用来描述Rest API的语言。
API 可以是使用yaml或json来表示。
Swagger API Spec包含以下部分: swagger,指定swagger spec版本
info,提供API的元数据
tags,补充的元数据,在swagger ui中,用于作为api的分组标签
host,主机,如果没有提供,则使用文档所在的host
basePath,相对于host的路径
schemes,API的传输协议,http,https,ws,wss
consumes,API可以消费的MIME类型列表
produces,API产生的MIME类型列表
paths,API的路径,以及每个路径的HTTP方法,一个路径加上一个HTTP方法构成了一个操作。每个操作都有以下内容: tags,操作的标签 summary,短摘要 description,描述 externalDocs,外部文档 operationId,标识操作的唯一字符串 consumes,消费的MIME类型列表 produces,生产的MIME类型列表 parameters,参数列表 responses,应答状态码和对于的消息的Schema schemes,传输协议 deprecated,不推荐使用 security,安全
definitions,定义API消费或生产的数据类型,使用json-schema描述,操作的parameter和response部分可以通过引用的方式使用definitions部分定义的schema parameters,多个操作共用的参数
responses,多个操作共用的响应
securityDefinitions,安全scheme定义
security,安全声明
externalDocs,附加的外部文档
一个操作描述的实例:
/pets/findByTags: get: tags: - pet summary: Finds Pets by tags description: Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing. operationId: findPetsByTags produces: - application/json - application/xml parameters: - in: query name: tags description: Tags to filter by required: false type: array items: type: string collectionFormat: multi responses: "200": description: successful operation schema: type: array items: $ref: "#/definitions/Pet" "400": description: Invalid tag value security: - petstore_auth: - write_pets - read_pets
二,Swagger UI
Swagger UI用于显示Rest接口文档。
访问在线Swagger UI:http://petstore.swagger.io/
如何使用?只要把github项目(https://github.com/swagger-api/swagger-ui)下载到本地:。然后用浏览器打开dist/index.html就可以。
git clone https://github.com/swagger-api/swagger-ui.git
ps:swagger ui支持中文版。方法是修改index.html,在head标签中添加如下代码,引入/lang/zh-cn.js
<script src='lang/translator.js' type='text/javascript'></script> <script src='lang/zh-cn.js' type='text/javascript'></script>
三,编辑器
Swagger Editor是Swagger API Spec的编辑器,Swagger Editor使用yaml进行编辑,但允许导入和下载yaml 和 json两种格式的文件。
下载发布版:https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip
解压,然后用HTTP Server将静态文件加载起来,下面是安装node.js的http server并跑起来的指令
npm install -g http-server wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip unzip swagger-editor.zip http-server -p 8080 swagger-editor
在浏览器中输入地址就可以进行编辑了
https://zhuanlan.zhihu.com/p/21353795
标签:Swagger,tags,描述语言,API,editor,https,swagger 来源: https://www.cnblogs.com/wayneliu007/p/10936494.html