Swagger的学习总结

Swagger:REST APIs文档生成工具。Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

是一种API设计工具,能更好地实现前后端分离:Swagger - 前后端分离后的契约 。

一些环境部署与搭建:

让接口测试成为合格的桥梁——本地搭建 Swagger-UI 环境搭建

Swagger入门教程

主要使用swagger-ui 和 swagger-editor。swagger-ui展示swagger-editor生成的api文档,api文档格式可以是yaml或json。(感觉是swagger-ui可以在线测试使用,交互;swagger-editor只是生成文档)


有关Swagger的一些个人理解:

Swagger是REST APIs文档生成工具。

主要的工作量应该在于Swagger文档的编写,而文档的编写需要遵循一定的规范,即Swagger API Spec。Swagger API Spec是Swagger用来描述REST API的语言,可以用YAML和JSON表示。

Swagger文档的编写可以采用以下方式:

(1)手动编写Swagger文档。要对SwaggerSpec很熟悉。可以利用在线编辑器Swagger editor(http://editor.swagger.io/#/)验证YAML格式的内容是否违反Swagger spec,Swagger editor会标出错误并且给予格式提醒。所以说手动编写要对YAML或者JSON语法非常熟悉。但是这种方法相对好上手。

(2)Swagger文档应该可以从代码注释中自动生成。目前在参考这个教程:http://michal.karzynski.pl/blog/2016/06/19/building-beautiful-restful-apis-using-flask-swagger-ui-flask-restplus/?utm_source=tuicool&utm_medium=referral。因为对API和FLASK等相关内容不太熟悉,还在学习中。

Swagger-UI是一套HTML/CSS/JS框架用于解析遵守Swagger spec的JSON或YML文件,展示swagger-editor生成的API文档,还可以在其中调试API。这是官方demo的地址:http://petstore.swagger.io/。

Swagger-UI界面也可以进行修改,包括进行中文配置等。

下面是一个比较好的Swagger-UI说明:Swagger-UI用户手册 。


FLASK

使用python的Flask实现一个RESTful API服务器端

近些年来,REST成为web services和APIs的标准架构。

python的Flask框架可以轻松实现一个RESTful服务。

Flask python web框架。

Flask很简单,micro-framework,所有有很多extensions配合使用,可以实现更多的功能。

Flask-RESTPlus:更方便地搭建REST APIs。核心功能是,可以结合Swagger UI自动生成交互性的API文档。

API的组织方式: API namespaces, RESTful resources 和 HTTP methods。
Namespaces:允许API定义划分为多个文件,每一个是API的一部分,用于不同的 URL prefix(前缀)。
RESTful resources:组织API成不同的endpoints(与不同的数据类型有关)


另外需要搞懂的一些点:

1. RESTful API

先理解API接口!!!

想问一下什么是API接口,具体是什么意思? -- 知乎

API(Application Programming Interface,应用程序编程接口)是一些预先定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码,或理解内部工作机制的细节。

简单的说,就是通过某一预先定义的渠道读/写数据的方式。

下面这篇算是解决了我的困惑==

利用「接口」做产品时我们该如何思考?

一般接口包含以下几个内容:

接口地址:顾名思义就是接口的地址,以网址的形式展现,你通过发送请求给这个网址来对接口进行交互操作。
请求方法:
请求参数:即传输参数的时候要带的一些参数,一般文档中会用表格的形式清晰的说明。当我向接口发送携带请求参数的请求时,都要携带什么字段,规则是什么。
返回内容:返回内容一般会以json或是XML的形式返回。
错误代码:

REST -- REpresentational State Transfer 直接翻译:表现层状态转移。

怎样用通俗的语言解释REST,以及RESTful?--知乎

REST描述的是在网络中client和server的一种交互形式;REST本身不实用,实用的是如何设计 RESTful API(REST风格的网络接口);【其实是要设计一种合适的API,RESTful的】

理解RESTful架构

总结一下什么是RESTful架构:

(1)每一个URI代表一种资源;

(2)客户端和服务器之间,传递这种资源的某种表现层;

(3)客户端通过四个HTTP动词,对服务器端资源进行操作,实现"表现层状态转化"。

2. Mock server

你可能感兴趣的:(Swagger的学习总结)