我家小花儿

这个屌丝很懒，什么也没留下！

热门标签

运用Swagger编写API文档_swagger api-doc编辑

作者：我家小花儿 | 2024-07-29 07:37:13

踩

swagger api-doc编辑

1 运用Swagger编写API文档

1.1 Swagger

1.1.1什么是Swagger

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

1.1.2 SwaggerEditor安装与启动

（1）下载 https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip。我在资源中已经提供。

（2）解压swagger-editor,

（3）全局安装http-server(http-server是一个简单的零配置命令行http服务器)

npm install -g http-server
1

（4）启动swagger-editor

http-server swagger-editor
1

（5）浏览器打开： http://localhost:8080

在这里插入图片描述

1.1.3 语法规则

（1）固定字段

字段名	类型	描述
swagger	string	必需的。使用指定的规范版本。
info	Info Object	必需的。提供元数据API。
host	string	主机名或ip服务API。
basePath	string	API的基本路径
schemes	[string]	API的传输协议。值必须从列表中:“http”,“https”,“ws”,“wss”。
consumes	[string]	一个MIME类型的api可以使用列表。值必须是所描述的Mime类型。
produces	[string]	MIME类型的api可以产生的列表。值必须是所描述的Mime类型。
paths	路径对象	必需的。可用的路径和操作的API。
definitions	定义对象	一个对象数据类型生产和使用操作。
parameters	参数定义对象	一个对象来保存参数,可以使用在操作。这个属性不为所有操作定义全局参数。
responses	反应定义对象	一个对象响应,可以跨操作使用。这个属性不为所有操作定义全球响应。
externalDocs	外部文档对象	额外的外部文档。
summary	string	什么操作的一个简短的总结。最大swagger-ui可读性,这一领域应小于120个字符。
description	string	详细解释操作的行为。GFM语法可用于富文本表示。
operationId	string	独特的字符串用于识别操作。 id必须是唯一的在所有业务中所描述的API。工具和库可以使用operationId来唯一地标识一个操作,因此,建议遵循通用的编程的命名约定。
deprecated	boolean	声明该操作被弃用。使用声明的操作应该没有。默认值是false。

（2）字段类型与格式定义

普通的名字	type	format	说明
integer	integer	int32	签署了32位
long	integer	int64	签署了64位
float	number	float
double	number	double
string	string
byte	string	byte	base64编码的字符
binary	string	binary	任何的八位字节序列
boolean	boolean
date	string	date	所定义的full-date- - - - - -RFC3339
dateTime	string	date-time	所定义的date-time- - - - - -RFC3339
password	string	password	用来提示用户界面输入需要模糊。

1.2 基础模块-城市API文档

1.2.1 新增城市

编写新增城市的API , post提交城市实体

URL： /city

Method: post

编写后的文档内容如下：

在这里插入图片描述

代码如下：

swagger: '2.0'
info:
  version: "1.0.0"
  title: 基础模块-城市API
basePath: /base
host: api.tensquare.com
paths:
  /city:
    post:
      summary: 新增城市
      parameters:
        - name: "body"
          in: "body"
          description: 城市实体类
          required: true
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: 成功
          schema:
            $ref: '#/definitions/ApiResponse'
definitions:
  City: 
    type: object
    properties: 
      id: 
        type: string
        description: "ID"
      name:
        type: string
        description: "名称"
      ishot:
        type: string
        description: 是否热门
  ApiResponse: 
    type: object
    properties: 
      flag: 
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息
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
36
37
38
39
40
41
42
43
44
45
46
47
48

编辑后可以在右侧窗口看到显示的效果

1.2.2 修改城市

URL： /city/{cityId}

Method: put

编写后的文档内容如下：

在这里插入图片描述

代码如下：

  /city/{cityId}:
    put:
      summary: 修改城市
      parameters:
        - name: cityId
          in: path
          description: 城市ID
          required: true
          type: string
        - name: body
          in: body
          description: 城市
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: 成功响应
          schema:
            $ref: '#/definitions/ApiResponse'  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

1.2.3 删除城市

删除城市地址为/city/{cityId} ，与修改城市的地址相同，区别在于使用delete方法提交请求

在这里插入图片描述

代码如下：（/city/{cityId} 下增加delete）

    delete:
      summary: 根据ID删除
      description: 返回是否成功
      parameters:
        - name: cityId
          in: path
          description: 城市ID
          required: true
          type: string
      responses:
        '200':
          description: 成功
          schema:
            $ref: '#/definitions/ApiResponse'
1
2
3
4
5
6
7
8
9
10
11
12
13
14

1.2.4 根据ID查询城市

URL: /city/{cityId}

Method: get

返回的内容结构为： {flag:true,code:20000, message:“查询成功”,data: {…} }

data属性返回的是city的实体类型

在这里插入图片描述

代码实现如下：

（1）在definitions下定义城市对象的响应对象

  ApiCityResponse:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      flag:
        type: "boolean"
      message:
        type: "string"
      data:
        $ref: '#/definitions/City'
1
2
3
4
5
6
7
8
9
10
11
12

（2）/city/{cityId} 下新增get方法API

    get:
      summary: 根据ID查询
      description: 返回一个城市
      parameters:
        - name: cityId
          in: path
          description: 城市ID
          required: true
          type: string
      responses:
        '200':
          description: 操作成功
          schema:
            $ref: '#/definitions/ApiCityResponse'
1
2
3
4
5
6
7
8
9
10
11
12
13
14

1.2.5 城市列表

URL: /city

Method: get

返回的内容结构为： {flag:true,code:20000, message:“查询成功”,data:[{…},{…},{…}] }

data属性返回的是city的实体数组

在这里插入图片描述

实现步骤如下：

（1）在definitions下定义城市列表对象以及相应对象

  CityList:
    type: "array"
    items: 
      $ref: '#/definitions/City'
  ApiCityListResponse:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      flag:
        type: "boolean"
      message:
        type: "string"
      data:
        $ref: '#/definitions/CityList'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

（2）在/city增加get

    get:
      summary: "城市全部列表"
      description: "返回城市全部列表"
      responses:
        200:
          description: "成功查询到数据"
          schema: 
            $ref: '#/definitions/ApiCityListResponse'
1
2
3
4
5
6
7
8

1.2.6 根据条件查询城市列表

实现API效果如下:

在这里插入图片描述

代码如下：

  /city/search:
    post:
      summary: 城市列表(条件查询)
      parameters:
        - name: body
          in: body
          description: 查询条件
          required: true
          schema:
            $ref: "#/definitions/City"
      responses:
        200:
          description: 查询成功
          schema:
            $ref: '#/definitions/ApiCityListResponse'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

1.2.7 城市分页列表

实现API效果如下：

在这里插入图片描述

实现如下：

（1）在definitions下定义城市分页列表响应对象

  ApiCityPageResponse:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      flag:
        type: "boolean"
      message:
        type: "string"
      data:
        properties:
          total:
            type: "integer"
            format: "int32"
          rows:
            $ref: '#/definitions/CityList'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

（2）新增节点

  /city/search/{page}/{size}:
    post:
      summary: 城市分页列表
      parameters:
        - name: page
          in: path
          description: 页码
          required: true
          type: integer
          format: int32
        - name: size
          in: path
          description: 页大小
          required: true
          type: integer
          format: int32
        - name: body
          in: body
          description: 查询条件
          required: true
          schema:
            $ref: "#/definitions/City"
      responses:
        200:
          description: 查询成功
          schema:
            $ref: '#/definitions/ApiCityPageResponse'
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