swagger（接口开发工具）介绍

翻译

百度翻译

从写文档开始说起

后台同事小波写了一堆 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写，文档更具有指导意义，开发方向有保证
• 后台写，可以自动生成，效率高，精准无误
• 前台写，接口给谁用的，你心里没点谱么？

自问自答

当然是自动生成咯 =.=! ，可怜的小波啊！！