Linuxword Global
当前位置: Linux技术 > 利用 swagger 管理 API 开发

利用 swagger 管理 API 开发

2024-11-12 分类：Linux技术 作者：Linux网站管理员 阅读（38）

swagger 可以通过 yaml 文件自动生成 api 文档，客户端代码等，减少了许多繁琐的工作和前后端沟通，从而提高开发效率。

第一次知道 swagger 这个工具， 是在 docker 的源码里，docker 客户端和服务端的 API 就是使用 swagger 来管理。最近在一次技术交流会上，听人提到用 swagger 来自动生成 api 文档，省下了许多前后端沟通的工夫，便留心记了下来。

前几天抽空研究了一下，发现使用 swagger 进行 api 开发，确实可以减少了许多繁琐的工作，大大提高开发和前后端沟通的效率。使用 swagger ，只要在项目里写好 swagger.yaml 文件，其他开发人员需要了解 api 的信息时，把它放到线上或下载下来的 swagger editor，就能自动生成 api 文档，调试接口，还可以生成多种语言的客户端代码、服务端代码。

swagger 最主要的优点，总结有以下几点：

  • 记录 api 信息只要一个 yaml 文件，用的时候放到 editor 就能直接生成文档。yaml 容易编辑维护
  • 可以生成多种客户端代码，客户端调接口只要传参数，简化使用方法
  • 可以在 editor 请求调试接口

Swagger yaml文件示例

Swagger 定义 api 的标准文件可以是 json 格式也可以是 yaml 格式，但是使用 yaml 可读性更高和更容易编写。

Swagger 目前最新版本是 OpenAPI 3.0 （ Swagger Specification 已经被捐献给 linux 基金会，更名为 OpenAPI Specification (OAS) ，因此 Swagger 和 OpenAPI 基本可以理解为一个东西），虽然 3.0 版本也可以生成的客户端代码，但支持语言没有 2.0 的多。本文还是使用一个 2.0 的 yaml 文件作为示例，介绍 swagger 的基本语法。不过，2.0 的 yaml 可以在 swagger editor 里自动转成 3.0。

api 文档的基本信息

Yaml 文件开头需要声明版本：

1

swagger: "2.0"

紧跟着是项目信息

1
2
3
4
5

info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT

然后是请求地址、格式等内容：

1
2
3
4
5
6
7
8

host: petstore.swagger.io
basePath: /v1
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json

consumes 和 produces 分别表示请求和返回的 Content-Type （本例是: Content-Type: application/json），接下的接口如果没有另外声明这两个字段，则都是这个格式。

在 yaml 定义一个 GET 请求接口

paths 字段可以定义具体接口请求方式、参数等，例如定义一个 GET /pets 接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          type: integer
          format: int32
      responses:
      	.....

在上面 yaml 片段中：

  • Summary 是接口介绍
  • operationId 作为该接口的唯一标识
  • tags 是给接口的归类
  • parameters 即请求参数，此处只有一个 limit 的接口，以 query 方式传递

接上一个 yaml 片段，返回格式是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

			responses:
        "200":
          description: A paged array of pets
          headers:
            x-next:
              type: string
              description: A link to the next page of responses
          schema:
          	type: array
          	items:
          		type: "object"
              required:
                - id
                - name
              properties:
                id:
                  type: integer
                  format: int64
                name:
                  type: string
                tag:
                  type: string
        default:
          description: unexpected error
          schema:
            type: "object"
            required:
              - code
              - message
            properties:
              code:
                type: integer
                format: int32
              message:
                type: string

在这个 yaml 片段里，分别定义Status Code 为 200 和其它的返回值。

schema 就是返回数据的格式，对应 200 的返回格式即是：

1
2
3
4
5
6
7

[
  {
    "id": 0,
    "name": "string",
    "tag": "string"
  }
]

POST 请求接口示例

因为请求路径相同， POST /pets 可以跟在 GET /pets 下方：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

paths:
  /pets:
    get:
      ...
      ...
		post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      parameters:
        - name: "pet"
          in: body
          description: creat a pet
          schema:
            type: "object"
            required:
              - id
              - name
            properties:
              id:
                type: integer
                format: int64
              name:
                type: string
              tag:
                type: string
      responses:
        "201":
          description: Null response
        default:
         ……

POST 请求的参数通过 body 传递，因此 parameters 写明 in: body, 最终生成的请求示例如下：

1
2
3
4
5

{
  "id": 0,
  "name": "string",
  "tag": "string"
}

使用 $ref 复用数据类型

对比 get 和 post 的 yaml 片段，可以发现其中有不少重复的内容，比如 parameters 和 response 的 scheme 多次出现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

				schema:
            type: "object"
            required:
              - id
              - name
            properties:
              id:
                type: integer
                format: int64
              name:
                type: string
              tag:
                type: string

这些可以定义一些可复用的数据格式，然后用 $ref 引入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

definitions:
  Pet:
    type: "object"
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      tag:
        type: string
  Pets:
    type: array
    items:
      $ref: '#/definitions/Pet'
  Error:
    type: "object"
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string

swagger yaml 基本的写法大致就是这样，最终完整的 yaml 文件见：uber.yaml

使用 swagger editor 生成文档、代码

swagger 有一些可以配套使用的工具，editor 就是其中之一。完成的 yaml ，任何时候想查看接口文档，只要把 yaml 文件放到 editor，就能自动生成 api 文档。

以下截图是放到 online editor 的效果: swagger-editor

在 editor 里还可以根据自己需要生成客户端代码，服务端代码。客户端代码可以类似 sdk 那样接入项目，调用时只要传入参数即可。

服务端代码是一个模版，帮你定义好最终输出数据的格式，而中间的实现逻辑，还需要自己完成。

swagger 的不足

swagger 总体上可以大大提高 api 开发的效率，不过试用的过程中，还是发现了美中不足之处。

  • 无法通过 json 数据自动生成 schema。

    写 yaml 文件毕竟还是要花一些时间，尤其是定义返回数据的schema。假如可以导入接口返回的 json 数据，自动生成 schema 的 properties 等信息，又会方便了许多。

「梦想一旦被付诸行动，就会变得神圣，如果觉得我的文章对您有用，请帮助本站成长」

赞(0) 打赏
一分也是爱

支付宝扫一扫打赏

微信扫一扫打赏

标签：

上一篇：

下一篇：

相关推荐

博客简介

本站CDN采用VmShell免费提供离中国大陆最近的香港CMI高速网络做支撑,ToToTel打造全球最快速的边沿网络支撑服务，具体详情请见 :https://vmshell.com/ 以及 https://tototel.com/,网站所有的文件和内容禁止大陆网站搬迁复制,谢谢,VPS营销投稿邮箱: admin@linuxxword.com，我们免费帮大家发布，不收取任何费用,请提供完整测试文稿!

最近更新

热门标签

news(120) soledad(120) VPS(63) 安装(43) vmshell(38) 搭建(37) 使用(36) 美国(33) 如何(33) linux(32) 教程(32) 日本(27) 服务器(27) 系统(22) 香港(21) 下载(20) GOOGLE(19) Wordpress(19) MYsql(18) 脚本(18) 免费(18) 中国(18) tototel(16) cloudflare(16)

精彩评论

友情链接

他们同样是一群网虫，却不是每天泡在网上游走在淘宝和网游之间、刷着本来就快要透支的信用卡。他们或许没有踏出国门一步，但同学却不局限在一国一校，而是遍及全球！申请交换友链

站点统计

  • 文章总数： 2590 篇
  • 草稿数目： 22 篇
  • 分类数目： 6 个
  • 独立页面： 0 个
  • 评论总数： 2 条
  • 链接总数： 0 个
  • 标签总数： 13020 个
  • 注册用户： 139 人
  • 访问总量： 8,655,254 次
  • 最近更新： 2024年11月21日