美文网首页
swagger(接口开发工具)介绍

swagger(接口开发工具)介绍

作者: 澄澄真可爱 | 来源:发表于2019-03-02 01:17 被阅读0次

    翻译

    百度翻译

    从写文档开始说起

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

    自问自答

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

    相关文章

      网友评论

          本文标题:swagger(接口开发工具)介绍

          本文链接:https://www.haomeiwen.com/subject/eqysuqtx.html