为什么要用 OpenAPI
本来叫“基于 swagger 撰写接口文档”，但是一番搜索阅读之后发现 swagger 已经抽象出了一套接口描述规范，并将其命名为 OpenAPI。在 OpenAPI Specification 的基础上，扩展了很多相关的工具集。
官方的说明文档在此，进一步说明文章网上到处都有。
swagger 工具集包括以下组成部分：
- 规范 - 整个体系的理论基础。
- Swagger Editor – 基于浏览器的所见即所得编辑器.
- Swagger UI – OpenAPI 文件生成交互式 API 文档
- Swagger Codegen – OpenAPI 文件生成客户端/服务端代码
- SwaggerHub - 协作平台，在集成了以上开源工具外增加了在线托管、分享等功能
- Swagger Inspector - 测试 API 和生成 OpenAPI 的开发工具
- 解决方案 - 组合一个或多个工具（包括其他闭源工具）解决接口的设计、开发、测试过程中遇到的问题
- 还有基于规范的其他开源工具，可以组合使用，例如导出 md 后再转成 word
如何使用/工作流程
先有接口后生成文档
- 整理已有的接口
- 生成静态的 OpenAPI spec
- 根据 OpenAPI spec 生成文档 / 使用在线的 Swagger UI 生成可交互文档
先有文档再写接口
- 在 Swagger Editor 中编写 OpenAPI spec
- 使用 OpenAPI spec 生成文档
- 使用 OpenAPI spec 生成代码
实战
现在的需求是写一份接口文档，docx ，接口还未实现。
注意：OAS 最新版是 3.0 ，但是很多开源工具只支持到 2.0 ，因此要按照 2.0 来写文档。
导出 md 需要根据文档添加配置。
- 在 http://editor.swagger.io/ 完成接口文档撰写
- 使用转 markdown 工具得到 md 文件 https://github.com/Swagger2Markup/swagger2markup-cli
- 在 http://coolaf.com/tool/md 得到 doc 格式文件
