Swagger 入门和实战

简介

Swagger 是最流行的 API 开发工具,它遵循 OpenAPI Specification(OpenAPI 规范,也简称 OAS)。

Swagger 可以贯穿于整个 API 生态,如 API 的设计、编写 API 文档、测试和部署。

Swagger 是一种通用的,和编程语言无关的 API 描述规范。

应用场景

  • 如果你的 RESTful API 接口都开发完成了,你可以用 Swagger-editor 来编写 API 文档( yaml 文件 或 json 文件),然后通过 Swagger-ui 来渲染该文件,以非常美观的形式将你的 API 文档,展现给你的团队或者客户。

  • 如果你的 RESTful API 还未开始,也可以使用 Swagger 生态,来设计和规范你的 API,以 Annotation (注解)的方式给你的源代码添加额外的元数据。这样,Swagger 就可以检测到这些元数据,自动生成对应的 API 描述信息。也就是说,Swagger 支持自动生成 API 文档。

Swagger 生态对 JAVA 的支持非常好,但对 PHP 的支持却略显不足。如果想要在 PHP 中自动生成 API 文档,可尝试使用 Swagger-php (目前仅兼容 Swagger 2.0 specification)。

规范

Swagger Specification(Swagger 规范),规定了如何对 API 的信息进行正确描述。

Swagger 规范,以前称作 Swagger Specification,现在称作 OpenAPI Specification(简称 OAS)。

Swagger 规范学起来也不难,想熟练使用 Swagger 就必须熟悉 Swagger 规范。

Swagger 规范本身是与编程语言无关的,它支持两种语法风格:

  • YAML 语法
  • JSON 语法

这两种语法风格可以相互转换,都可以用来对我们的 RESTful API 接口的信息进行准确描述,便于人类和机器阅读。

在 Swagger 中,用于描述 API 信息的文档被称作 Swagger 文档。

Swagger 的规范主要有两种:

  • Swagger 2.0
  • OpenAPI 3.0

OpenAPI 3.0 规范是在 2017 年发布的,它在 Swagger 2.0 的基础上进行了优化,包括废弃某些关键词(host、basePath等),新增了一些关键词(servers、components、securitySchemes 等)。

OpenAPI 3.0 比 Swagger 2.0 更强大,使用起来更加灵活、方便。推荐使用 OpenAPI 3.0 。

关于 Swagger 规范的详细信息,请参考官方文档 https://swagger.io/docs/ 。

Swagger 文档

Swagger 文档(文件),指的是符合 Swagger 规范的文件,用于对 API 的信息进行完整地描述。

Swagger 文档是整个 Swagger 生态的核心。

Swagger 文档的类型有两种:yaml 文件和 json 文件。

yaml 文件用的是 YAML 语法风格;json 文件用的是 JSON 语法风格。这两种文件都可以用来描述 API 的信息,且可以相互转换。

Swagger 文档(swagger.json 或 swagger.yaml)中关于 API 的描述必须符合 Swagger 规范,Swagger 文档是整个 Swagger 生态的核心。

简单的说,Swagger 文档就是 API 文档,只不过 Swagger 文档是用特定的语法来编写的。Swagger 文档本身看起来并不美观,这时,就需要一个好的 UI 工具将其渲染一番,这个工具就是 Swagger-ui。

我们可以用任何编辑器来编写 Swagger 文档,但为了方便在编辑的同时,检测 Swagger 文档是否符合规范,就有了 Swagger-editor 编辑器。

工具

Swagger 生态主要包含以下几种工具:

  • Swagger-editor 是一种编辑器,用于编写 Swagger 文档,还支持文档实时检测、API 调试等功能。
  • Swagger-ui 是一种 UI 渲染工具,用于渲染 Swagger 文档,以提供美观的 API 界面。
  • Swagger-codegen 是一种代码生成器,可基于 Swagger 文档,来构建服务器端 stub 和 客户端 SDK。

Swagger-editor

Swagger-editor 主要用于编写符合 Swagger 规范的 RESTful API 文档,即编写 Swagger 文档。

Swagger-editor 是一个编辑器,可编写 Swagger 文档,来准确描述 API 信息。

Swagger-editor 可采用两种语法风格:

  • YAML 语法
  • JSON 语法

当然,不使用 Swagger-editor 也可以,你可以使用任何编辑器来编写 Swagger 文档。

Swagger-editor 的功能

  • 编写 Swagger 文档
  • 实时检测 Swagger 文档是否符合 Swagger 规范
  • 调试 Swagger 文档里描述的 API 接口
  • 转换 Swagger 文档(yaml 转 json,或 json 转 yaml)

可见,Swagger-editor 编辑器比一般的编辑器更适合编写 Swagger 文档。当然 Swagger-editor 的功能还不止上面这些。因此,推荐使用 Swagger-editor。

Swagger-editor 的安装和使用

Swagger-editor 有两种方式使用:

  • 5
    点赞
  • 28
    收藏
    觉得还不错? 一键收藏
  • 1
    评论
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值