API生命周期第二阶段——设计：采用swagger进行API描述、设计

本篇博客主要是以swagger为依托，介绍API生命周期的第二个阶段——设计！在详细介绍之前，我必须声明一点：如果是想了解swagger和项目框架的集成的，这里没有。我要介绍的swagger进行的API描述，还处于API设计阶段，没有到第三阶段的实施呢（具体的分析，请看本篇博客第四部分：总结）。但如果你想了解各种集成，建议你直接百度，很多实例。

另外，本篇博客，没有具体的介绍swagger的定义，主要是从具体的开发现状中引出的这种工具去解决问题。 如果需要swagger的宏观定义说明，请参考：https://swagger.io/

一、一些场景

1，在开发的过程中，老是有人问你服务的地址。关于服务的调用地址，说了一遍又一遍。还有，关于参数的位置，类似于：“你这个参数是写在路径里的？”“你这个参数是写在URL请求参数里的？”“你这个参数到底是写在哪儿了？”“我期待的返回数据不是这样的！！！”“我要的返回值类型也不是这样的！！！”“这个返回码是什么意思来着？？？” 这样的问题，听第一遍的时候，心情很复杂，听多遍的时候，没有心情。

2，会专门用时间，前端工程师和后端工程师核对接口（得注意了，核对接口而已，并没有一个可视化的方式，告诉前端工程师每个接口的实操情况）。先不管本次核对是否高效并且有效，关键问题是：拿出了专用时间用于前后端工程师核对接口定义（还必须是本人到场确认）。

3，很多的接口文档，很多的接口描述规范，它们甚至不是一个入口。

4，接口被私自篡改，你不知道哪个接口正在使用，哪个接口已经成为过去式。当实施代码更更改之后，更恐怖的是，根本没来得及（我更愿意说是因为来不及）修改相应的接口文档。

5，API文档的版本控制（只是文档的版本）

6，接口的访问权限说明难以描述

7，前端等待后端实施结束，再次确认服务地址，前面的几个点开始循环了。。。。。。

8,9,10......

有没有其中一个，是你特别想干掉它的？？？？？  有没有抱怨过：当时写代码之前又不说有问题，现在代码写完了又说不对，为什么当时不说清楚她们前端那伙人到底想要什么。

事实上第一点就已经让我崩溃了好几次！！！

二、API描述

接下来，主要是讲swagger editor！

关于API 有几个比较关键的概念：API描述、API发现、API档案   接下来咱们一个一个的解决问题：

总结起来以上一些场景（额，实话说，那就是我目前开发中所面对的。我们用了更多的时间去反复确认，甚至抱怨争吵一些本不应该的点。耗费了一次又一次的时间，却仍然没有得到一个有效的解决。当然，从之前的无接口文档——有文档无规范——有接口定义规范——在线规范文档——  我们已经成长了很多），它们一个很大的根源在于两点：

1，语义规范的API描述：参数是否必需，参数位置，参数类型，请求路径，请求权限，请求协议，方法返回值，方法返回类型，状态码含义等等

2，可视化的API mock 测试：当我请求这个rest API接口时，它到底会返回什么？它究竟是不是我想要的？？？（注意了，因为需求变动而产生的API接口重定义，和因为沟通不清楚而导致的废弃再定义，这两个是不一样的概念）

 

那么，swagger可以帮我们做什么？？先看一个宏观的思维导图吧：

 

往简单了说吧：1，规范的API定义

 

schemes:
 - https
consumes:
 - "application/json"
produces:
 - "application/json"
paths:
  /resources/api/tb-build:
    post:
     tags:
       - "建筑"
     description: "新增一个建筑"
     operationId: "addBuild"
     produces: 
       - "json"
     parameters:
      - in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Build"
     responses:
        200:
          description: "新增建筑成功！"
        404:
          description: "找不到API服务"
        default:
          description: "未知错误"

这是一段我刚写简单的API描述，关于这个接口的定义，有什么不清楚的没？？？额，具体内容都可以写中文哈，除了左侧的语义描述！更为详细的API描述，请参考：
http://editor.swagger.io/?_ga=2.123928330.1613166242.1502105842-171987874.1501570940#/

 

三， 可视化的API mock 测试

 

咱们现在看一下对于上述接口的mock测试：


在swagger的mock测试中，可以在线可视化立即测试所编写的API接口实操情况。
做mock service Test 的意义是什么？？？ 大家可以思考，尤其是这一步是在代码实施之前。 由于它是一个在线的可视化mock测试，前后端工程师可以不必在物理区域在一起。更由于swagger的API协作合并，当发现某一个API描述有问题时，某一方可以在组织下重建它所期待的描述，然后最终合并通知！

 

四、总结

对于swagger的使用阶段
swagger可不可以在代码实施的时候集成使用？？？
可以，但是，这需要确定快速构建部署，可快速修改！  明白什么意思没呢？？？  试着考虑一下，开发了很久，才开发完，API的对应文档出炉，然后别人再根据文档调用？？？？额，如果能在管理上让别人不闲着，好像也没什么要紧哈。  那我们来确认第二点，你老人家吭哧坑次开发了好久，文档也出来了，然而你提供的，根本不是别人想要的，呵 呵 哒！！！
其实，这一点也是我们后面会说到的第三阶段具体实施的三种不同模式的区别。 在实施之前运用swagger设计API，这是design -first，将swagger集成到代码实施，这是code -first，还有一种是API -first，具体的，咱们在第三阶段进行说明。