翻译
百度翻译
从写文档开始说起
后台同事小波写了一堆 RESTful接口，作为一个前端开发，我让他给我写一个API文档，大概是这样的
get: /user/list
描述：查询年龄在 [m，n]之间的用户
入参：
ageMax:?number，
ageMin:?number
样例报文：
200 [{name:'张三',age:13},{name:'李四',age:13}]
400 {msg:'最小年龄不能为负数',code:'410'}
小波按我的要求写完文档，我自己对接口，发现接口各种调不同，跟小波确认，不是这个字段缺了，就是那个字母写错了，费了九牛二虎之力才把工作完成。
项目经理见到这种情况，给我们建议，先写文档，然后前后端完全按照文档开发，这样联调的时候错误较少，并行开发也能大大提升开发效率。
面向接口开发
于是，面向接口开发的流程就此确定，日积月累，我们的接口文档越来越完善，最终固化成标准 Open API。
大概长下面这样：[完整版]https://petstore.swagger.io/v2/swagger.json
"paths": {
"/user/{username}": {
"get": {
"tags": [
"user"
],
"summary": "Get user by user name",
"description": "",
"operationId": "getUserByName",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "username",
"in": "path",
"description": "The name that needs to be fetched. Use user1 for testing. ",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"$ref": "#/definitions/User"
}
},
"400": {
"description": "Invalid username supplied"
},
"404": {
"description": "User not found"
}
}
},
"put": {
"tags": [
"user"
],
"summary": "Updated user",
"description": "This can only be done by the logged in user.",
"operationId": "updateUser",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "username",
"in": "path",
"description": "name that need to be updated",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Updated user object",
"required": true,
"schema": {
"$ref": "#/definitions/User"
}
}
],
"responses": {
"400": {
"description": "Invalid user supplied"
},
"404": {
"description": "User not found"
}
}
},
"delete": {
"tags": [
"user"
],
"summary": "Delete user",
"description": "This can only be done by the logged in user.",
"operationId": "deleteUser",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "username",
"in": "path",
"description": "The name that needs to be deleted",
"required": true,
"type": "string"
}
],
"responses": {
"400": {
"description": "Invalid username supplied"
},
"404": {
"description": "User not found"
}
}
}
}
}
看的眼花，那就做个UI吧
于是我做了个swagger-ui项目，把这个又长又丑的json展示出来。项目经理觉得不错，说加个按钮，点击的时候直接去调用就可以方便测试了。经过不断的完善，又增加了折叠显示，测试接口，导出文档等功能。
image.png
测试开心了，小波写文档天天加班
聪明的小波，怎么会被区区文档吓到，只听他说，看我自动用代码生成文档。没过几天，生成工具swagger-codegen就做好了。听他说，大概是用java注解提供接口元信息，最后把这些注解读取汇总生成出来的。瞬间小波在我心中的地位又升华了。
SE也要编辑，没问题！
http://editor.swagger.io/ 在线编辑工具
https://github.com/swagger-api/swagger-editor
留个讨论问题，API文档应该由谁写？
- SE写，文档更具有指导意义，开发方向有保证
- 后台写，可以自动生成，效率高，精准无误
- 前台写，接口给谁用的，你心里没点谱么？
自问自答
当然是自动生成咯 =.=! ，可怜的小波啊！！