Swagger简单使用心得

Swagger简单使用心得

这里指的是那个在线的 Swagger Editor 网站，不是本地的。在线的用得多舒服呀

---

为什么要使用 Swagger

在正规的项目开发中，API 接口文档有着极其重要的作用，一份好的 API 文档能大大简化开发的难度，因为 API 文档就是架构设计的体现，良好的架构设计与开发息息相关；同时，一份好的 API 文档还能大大降低沟通成本，节约开发时间。

但是，编写 API 文档本身就是一个相当费事费力的工作，要想编写一份好的 API 文档，不光要有好的文字组织能力，还要有长远的眼光，以及丰富的开发经验。

传统的 API 开发更是如此，书写过程耗费时间，而且开发前期可能需要经常调整接口的访问方式、需要的参数、返回的结果以及文字描述等，容易造成文档更新不及时，进而导致前后端双方沟通成本上升。

现在一些主流的 API 设计工具着重解决的问题就是如何更好地自动化生成 API 文档，大大节约了文档编写时间，并且可以很容易将测试也集成进来。

现在比较好的主流的 API 设计工具主要有两个，分别是 Swagger 和 Postman。这里用 Swagger 是因为之前接触过一些；Postman也挺不错的，更加轻量，可自行了解。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

简单说，就是一个兼接口编写、文档编写、交互测试于一身的功能强大的 API 设计/管理 工具，提供了多种编程语言的前后端分离解决方案。

它长这样：

这是我们 包包赚众包平台 项目的部分api，更详细的可以去我们的 API 文档 查看。

一些基本语法

主要就是通过键值对来定义文档，这些键值对都编写在一个 yaml 文件中，在线的 Swagger Editor 可以根据 yaml 自动生成动态可交互的 API 文档。

定义数据结构

一些经常要复用到的数据结构，可以把它们定义成一个组件，在要使用的地方引用即可。当然不定义在语法上也说得过去，但是会增加很多重复的代码，而且修改起来麻烦，改一个地方全都得改。

components:
  schemas:
    
    ...
    
    task:
      type: object
      description: Task info
      properties:
        id:
          type: string
          description: Task id, which is given after publishing, only can be empty before publishing
        publisher_id:
          type: string
          description: User id of the publisher
        name:
          type: string
          description: Task name
        brief_info:
          type: string
          description: Brief information of the task
        type:
          type: string
          description: Task type, questionnaire is "q", data collection is "d", recruitment is "r"
        contact:
          type: string
          description: Contact of the publisher
        requirements:
          type: object
          description: The types of target people, in json format
        tag_id:
          type: integer
          description