Update:

• 2019-03-06: swagger protocol 是2.0版本，属于swagger。3.0版本更名为openapi，属于Linux Foundation。同时swagger-codegen更名为openapi-generator。使用3.0。由于维护脚本重度依赖sh，平台使用windows linux subsystem。文章作废。

背景

• 个人开发者
• 迭代频繁
• 周期紧

技术名词

• OAS:
  • OpenAPI Specification
  • 当前两个流行restful api spec之一，另一个是RAML.
  • RAML 项目完成度稍逊，OAS脱胎自swagger，自动兼容swagger开源项目swaggerui, swagger-codegen等。
• Swagger
  • Swagger, The Best APIs are Built with Swagger Tools
  • 没怎么用过。

实践内容

1. 使用OAS描述restful api,
2. 使用swagger-edit, swagger-codegen生成代码骨架。
3. 使用Postman import OAS yml, 生成functional test.
4. [TBA], 为swagger-codegen增加语言支持。

实践细节

OAS描述restful api

1. spec细节参见OpenAPI Specification
2. editor:
   a. 使用在线版 [https://editor.swagger.io/] (我没这么做)
   b. 使用docker image.
   c. [TODO] 配合custom代码，自己搭建docker image.

使用swagger-edit, swagger-codegen生成代码骨架。

Details not important.

使用Postman import OAS yml, 生成functional test.

Details not important.

[TBA], 为swagger-codegen增加语言支持。

Not figured out yet.