简介（未完成）
在api 文档方面，痛点是啥，理想姿势是啥？
| 程序员的痛点 | swagger方案 |
|---|---|
| 不想写文档 | 写一点注解 |
| 文档太乱 | openapi ==> web ui |
| 代码改了，常常忘记改文档 | 自动生成；注解与代码在一起 |
| 调个接口看下效果要自己写curl | 接口调用界面 |
swagger体验
使用
本地创建一个springmvc 项目，假设项目根地址为 http://localhost:8080/swagger-demo，则针对controller 的如下代码
@Controller
@RequestMapping("/hello")
public class HelloController {
@RequestMapping(value = "/world", method= RequestMethod.GET)
@ApiOperation(value = "根据id获取user信息", notes = "")
@ResponseBody
public String showUser(Integer id){
User user = new User();
user.setId(1);
user.setAge(100);
user.setName("test");
return JSON.toJSONString(user);
}
}
则访问http://localhost:8080/swagger-demo/swagger-ui.html
- 可以查看接口信息，包括接口描述、入参、返回值
- 访问该接口 对应的curl 命令
- 输入id值，可以触发该请求的实际调用
缺点
- swagger 依赖太多，跟已有的项目有很多jar 冲突。
- 根据注解识别接口的返回值，很方便，但也导致接口 很难用object 之类 的父类了。
OpenAPI规范
使用yaml/json 统一来描述一个api 接口的各方面信息
编辑器 支持JSON vs YAML 方式编写 api 文档，有点像markdown 的感觉。
- 编辑器 是左侧yaml/json，右侧是接口页面
- markdown 是左侧 符合一定约定的txt，右侧是文档页面
干啥的/解决什么问题的/都有啥
观察 swagger 在github 上的项目，有4个Repository
- swagger-ui
- swagger-editor
- swagger-codegen
- swagger-core
分别干啥的？