引荐一款接口 API 设计神器!

引荐一款接口 API 设计神器!

今天给我们引荐一款接口 API 设计神器,传说中的,牛逼哄洪的 Swagger,它究竟是什么?今天为我们揭开谜底!

作者:栈长来历:|2019-02-25 10:18

今天栈长给我们引荐一款接口 API 设计神器,传说中的,牛逼哄洪的 Swagger,它究竟是什么?今天为我们揭开谜底!

Swagger是什么?

官网:

Swagger 如官网所示,它是最好的 API 构建东西。

它是一个围绕 OpenAPI 规范构建的开源东西,它可以协助我们设计、构建、记载和使用 REST API 接口。

Swagger 包括的主要套件:

Swagger Editor - 基于阅读器的修改器,用来编写 OpenAPI 规范。 Swagger UI - 基于 OpenAPI 规范动态生成 API 规范文档。 Swagger Codegen - 个模板驱动引擎,用来生成客户端代码。

图片来历见博客水印。

OpenAPI是什么?

上面有说到 Swagger 是一个围绕 OpenAPI 规范构建的开源东西,那么 OpenAPI 是什么呢?

OpenAPI 规范,曾经叫 Swagger 规范。它是一个为 REST APIs的接口界说的规范。OpenAPI 可以界说的 API 实体内容包括以下几个部分。

请求地点(如:/user) 请求类型(如:GET、POST 等) 请求参数 呼应参数 验证方式 文档信息:如联络人、答应证、效劳条件等

这个 OpenAPI 规范可以用 YAML 或者 JSON 来编写,这种格局十分易于学习,可读性对开发人员十分友爱。

完好的 OpenAPI 规范可以去官网看一下。

编写文档地点:

为什么需要Swagger?

现在的互联网架构都是前后端别离的模式,还有现在是移动互联网时代了,APP 需要与后端效劳器通讯也需要维护一套接口,API文档天然就成了前后端开发人员联络的纽带。

编写 API 文档的方式也各有不同,有用 WORD 编写的,有用 confluence 等编写的,但这些方式都不能动态更新,每次接口变更都需要手动维护文档,甚是麻烦。有了 Swagger,可以先做完接口,通过 Swagger 来动态生成和更新 API 文档。

后边的文章会继续介绍怎么使用 Swagger 注解来主动生成 API 文档,及怎么集成 Spring Boot 来应用实战。

【修改引荐】


本书描述的是在逆向与反逆向之间打开的一场旷日耐久的拉锯战。作者Eldad Eilam以一个解说人的身份为我们翔实地评述了两边使用的每一招每一...