实话说，Swagger Spec 提供了一套比较容易理解的 API 约定， 利用 Git 工具可以很快的就看到变更。我将再本文中提供一个中文示例，这样大家就能快速地上车。
以下是一个swagger 2.0 的 yaml 示例，你可以基于该示例来快速学习 swagger 2.0 文档编写。
以下是一个 OpenAPI 3.0 的 yaml 示例，推荐你结合 OpenAPI 3.0 规范中文版 来一起学习。
以上就是 Swagger 2.0和 OpenAPI 3.0 的示例 Yaml。
用过了 Swagger Editor 会发现，编辑调整 Swagger 必须得非常小心，特别是涉及复杂的 Schema。这里我强烈推荐 Apifox , 它是 API一体化平台，功能囊括了 API 设计， 调试，自动化测试和 API 文档协作， 它比较适合现代的开发方式，无论你是设计优先还是代码优先。你可以在 Apifox 中一边设计并调试 API ，一遍学习 OpenAPI 规范，在实践中学习会让你掌握得更快更扎实。
Apifox 是区分接口设计和接口运行两个概念的。
接口设计：即 新建接口 界面或接口详情里的 编辑 界面，用途是 定义接口文档规范，而不是 运行 接口，所以该界面是只能定义接口基本信息、参数名及参数说明等，而不能设置参数值。参数值、前置脚本/后置脚本 等信息请在接口运行>界面或接口用例界面填写。
接口运行：即接口详情里的「运行」界面，用途是调试接口，确保你的接口是可以正常运行的。
大家可以体验下，Apifox 对于初学者是非常友好的，可视化的界面让你能够快速的入门 API 设计！
