Swagger简单使用心得

最新推荐文章于 2024-11-13 18:42:32 发布

Wonderful_sky

最新推荐文章于 2024-11-13 18:42:32 发布

阅读量1.5k

点赞数

分类专栏：系统设计后端编程说明文感想心得文章标签： swagger api 语法设计

本文链接：https://blog.csdn.net/Wonderful_sky/article/details/94331643

版权

Swagger 是一个用于生成、描述、调用和可视化的 RESTful 风格 Web 服务的框架，提供接口编写、文档编写和交互测试功能。通过 YAML 文件定义接口，可以自动化生成动态可交互的 API 文档，简化 API 文档编写，减少前后端沟通成本。基本语法包括定义数据结构、通用返回头和路由，支持组件引用、请求类型、路由参数等。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

Swagger简单使用心得

文章目录

Swagger简单使用心得

@[toc]

为什么要使用 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: The tag id of the task
        ddl:
          type