Swagger:Rest API的描述语言
Swagger是一种Rest API的 简单但强大的表示方式,标准的,语言无关,这种 表示方式不但人可读,而且机器可读。 可以作为Rest API的交互式文档,也可以作为Rest API的形式化的接口描述,生成客户端和服务端的代码。
本文介绍Swagger以下内容:
- Swagger API Spec,描述Rest API的语言
- Swagger UI,将Swagger API Spec以HTML页面展现出来的模块
- Swagger Editor,Swagger API Spec的编辑器
Swagger API Spec/Open API Spec
Swagger API Spec是Swagger用来描述Rest API的语言,类似于描述Web服务的WSDL。Swagger API可以使用yaml或json来表示。 2016年1月,Swagger将Spec捐献给Open API Initiative (OAI),成为Open API Spec的基础。
Swagger API Spec包含以下部分:
- swagger,指定swagger spec版本,2.0
- 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:- petsummary: Finds Pets by tagsdescription: Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.operationId: findPetsByTagsproduces:- application/json- application/xmlparameters:- in: queryname: tagsdescription: Tags to filter byrequired: falsetype: arrayitems:type: stringcollectionFormat: multiresponses:"200":description: successful operationschema:type: arrayitems:$ref: "#/definitions/Pet""400":description: Invalid tag valuesecurity:- petstore_auth:- write_pets- read_pets
参数的描述包括:
- name,名字
- description,描述required,是否必须
- in,位置
- Path
- Query
- Header
- Body
- Form
- (对于Body类型的参数)
- schema,数据类型,可以详细描述,也可以引用definition部分定义的schema
- (对于Body类型以外的参数)
- type,类型
- format,数据格式
- allowEmptyValue,是否允许空值
- items,对于Array类型
- collectionFormat,对于Array类型
- default,缺省值
Swagger API Spec对你Rest API的每一个操作的请求消息的参数(Path,Query,Body,Form),响应消息的状态码和消息体的json结构都进行了详细的描述。不仅可以供给使用API的开发者学习,而且是对Rest API接口的形式化的抽象。
我们完全可以把Swagger API Spec当作一个API接口的设计语言,就像CORBA IDL或Web服务的WDL一样,先定义Rest API的操作参数和应答消息,再着手实现这些Rest API,这对Rest API日后的维护也提供了一个设计文档。
Swagger UI
Swagger UI是Swagger中用于显示Rest接口文档的项目,项目由一组HTML,JavaScript和CSS组成,没有外部依赖。Swagger UI可以根据Swagger Spec的json动态生成漂亮的帮助文档。支持常见浏览器。
Swagger UI如下图所示:
<img src="https://pic3.zhimg.com/d1387291921f6359427f9afe2d3800d9_b.jpg" data-rawwidth="1346" data-rawheight="668" class="origin_image zh-lightbox-thumb" width="1346" data-original="https://pic3.zhimg.com/d1387291921f6359427f9afe2d3800d9_r.jpg"> 可以访问在线Swagger UI: http://petstore.swagger.io/
使用Swagger UI很容易,只要把github项目(https://github.com/swagger-api/swagger-ui)下载到本地:
git clone https://github.com/swagger-api/swagger-ui.git
然后用浏览器打开dist/index.html就可以。当然也可以放到HTTP Server下通过HTTP协议访问。
在浏览器地址栏中,可以在index.html后添加url参数,就可以自动打开指定的Rest APi的json描述。如:file:///E://swagger-ui/dist/index.html?url=http://petstore.swagger.io/v2/swagger.json
通过编辑index.html,就可以对Swagger UI进行定制,包括:
1. 中文显示
在html header中添加下面的文字。
<script src='lang/translator.js' type='text/javascript'></script>
<script src='lang/zh-cn.js' type='text/javascript'></script>
中文翻译位于/lang/zh-cn.js文件,如果有什么不合适的翻译,可以直接修改。
2. 指定Swagger UI的表现方式
比如:
- docExpansion:指定操作的描述是收起的还是展开的
- supportedSubmitMethods:允许哪些HTTP方法的文档带Try It!的按钮
- operationsSorter:指定操作安装什么排序
更多请参考官网的文档。
Swagger Editor
顾名思义,Swagger Editor是Swagger API Spec的编辑器,Swagger API Spec有2中格式,yaml和json,Swagger Editor使用yaml进行编辑,但允许导入和下载两种格式的文件。在yaml编辑器的右面有所见即所得的预览。
&lt;img src="https://pic4.zhimg.com/25f853d5971826411bfcf9ee948f3a44_b.jpg" data-rawwidth="1365" data-rawheight="646" class="origin_image zh-lightbox-thumb" width="1365" data-original="https://pic4.zhimg.com/25f853d5971826411bfcf9ee948f3a44_r.jpg"&gt;
Swagger Editor的Live Demo:Swagger Editor
Swagger Editor的安装也很方便,
下载最新的发布版: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
http server启动后,就可以在浏览器中输入地址进行编辑了。
文件菜单提供了主要的功能
- New,创建新的文件
- Open Example,打开内建Swagger API Spec的示例
- Paste Json,将剪贴板的内容贴到编辑器中,取代当前的内容。在Paste之前一定要先下载编辑中的内容
- Import URL/Import File,导入已有的Swagger API Spec,可以是yaml或json格式的
- Download YAML/Download JSON,将编辑的结果下载到本地。
代码生成
Swagger支持根据Swagger API Spec生成客户端和服务端的代码,支持很多语言和框架。这部分我还没有深入使用。
参考文档
- GitHub - swagger-api/swagger-ui: Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
- GitHub - swagger-api/swagger-editor: Swagger Editor
- GitHub - swagger-api/swagger-codegen: swagger-codegen contains a template-driven engine to generate client code in different languages by parsing your Swagger Resource Declaration.
- OpenAPI-Specification/2.0.md at master · OAI/OpenAPI-Specification · GitHub
- JSON Schema - Documentation
- http://petstore.swagger.io/v2/swagger.json,Swagger API Spec的官方示例
本文转自https://zhuanlan.zhihu.com/p/21353795,所有权利归原作者所有。
Swagger:Rest API的描述语言相关推荐
- 【效率专精系列】善用API统一描述语言提升RestAPI开发效率
团队内部RestAPI开发采用设计驱动开发的模式,即使用API设计文档解耦前端和后端的开发过程,双方只在联调与测试时耦合.在实际开发和与前端合作的过程中,受限于众多因素的影响,开发效率还有进一步提高的 ...
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- SpringBoot——SpringBoot集成Swagger生成API文档
文章目录: 1.写在前面 2.步骤详解 2.1 pom文件中添加Swagger依赖 2.2 在application.properties核心配置文件中配置Swagger 2.3 编写需要生成API文 ...
- SpringBoot整合Swagger测试api构建
@Author:SimpleWu 什么是Swagger? Swagger是什么:THE WORLD'S MOST POPULAR API TOOLING 根据官网的介绍: Swagger Inspec ...
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api(二十)
一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring r ...
- 基于 abp vNext 和 .NET Core 开发博客项目 - 再说Swagger,分组、描述、小绿锁
基于 abp vNext 和 .NET Core 开发博客项目 - 再说Swagger,分组.描述.小绿锁 https://github.com/Meowv/Blog 在开始本篇正文之前,解决一个 @ ...
- 多维数组的行优先和列优先, 数据描述语言
多维数组的行优先和列优先 这里以numpy为工具,介绍一下多维数组的行优先和列优先的概念. 首先我们生成一个3x4的数组: arr = np.arange(12).reshape(3,4) 它的形状是 ...
- 云计算论文集, Spark, 数据描述语言, 运维工具集
https://antkillerfarm.github.io/ 云计算论文集 这里列出一些在这个领域产生重大影响的论文.仅作备忘,肯定不全,Google是其中的绝对主力. CAP <Towar ...
- 基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档(上篇)
前言 为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...
最新文章
- C# 回发或回调参数无效
- 数组-移除元素(交换移除)
- matlab 冒号操作符
- python 列表元素操作 push()和append()的区别
- html ip输入框效果,html5 input文本框输入动画特效
- 串口服务器接入232显示乱码,串口服务器出现乱码时如何处理,解决方案
- 漫画:混乱的标记语言XHTML2/HTML5
- 如何管理好IDC机房?(一)
- 你需要明白的SQL SERVER书签查找(Bookmark Lookup)
- xrd连续扫描和步进扫描_深度解析XRD
- Jellybean 4.1.1 精简列表+谷歌服务包精简列表
- 运维学习部分基础知识概括
- 安卓玩机搞机之卡刷包 线刷包与刷机中一些故障解决与问题分析
- 网络操作系统项目教程----Windows server 2003篇----服务器远程管理与监控
- 从0到1构建计算机(4/12)--时序逻辑芯片:时序门、寄存器、RAM、计数器
- java计算两个月份差_Java编程实现计算两个日期的月份差实例代码
- Linux环境搭建基础(二)
- Android限制录制屏幕无声音,哪一个安卓录屏软件可以录制系统的声音
- 编译原理知识点总结——识别单词的DFA
- DOCKER04_详解Dockerfile基本指令、FROM、LABEL、RUN、CMD、ENTRYPOINT、ARG、ENV、VOLUME、USER