一.什么是swagger
隨着互聯網技術的發展,前后端技術在各自的道路上越走越遠,他們之間的唯一聯系變成了api接口,api接口文檔編程了前后端人員的紐帶,而swagger就是書寫api文檔的一款框架.
相關資源下載地址: https://download.csdn.net/download/zhixingwu/12008773
推薦: 也可以使用 showdoc來書寫api文檔. 官網: https://www.showdoc.cc/
二.SwaggerEditor的安裝與啟動
- 下載 swagger-editor.zip
- 解壓swagger-editor
- 全局安裝http-server(http-server是一個簡單的零配置命令行http服務器)
npm install ‐g http‐server
- 啟動swagger-editor
http‐server swagger‐editor
- 瀏覽器打開： http://localhost:8080
三.語法規則
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 | 解釋操作的行為 |
| 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 | stirng | binary | 任何的八位字節序列 |
| boolean | boolean | ||
| date | string | date | 所定義的full-date- - - - - -RFC3339 |
| datetime | string | date-time | 所定義的date-time- - - - - -RFC3339 |
| password | stirng | password | 用來提示用戶界面輸入需要模糊 |
四.示例-城市API文檔
swagger: '2.0'
info:
version: "1.0.0"
title: 基礎模塊-城市API
host: api.pcloud.com
basePath: /base
paths:
/city:
post:
summary: 新增城市
parameters:
-
name: body
in: body
description: 城市實體類
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功響應
schema:
$ref: '#/definitions/ApiResponse'
get:
summary: 返回城市列表
responses:
200:
description: 成功響應
schema:
$ref: '#/definitions/ApiCityListResponse'
/city/{cityId}:
put:
summary: 修改城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
- name: body
in: body
description: 城市實體類
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功響應
schema:
$ref: '#/definitions/ApiResponse'
delete:
summary: 根據ID刪除城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
responses:
200:
description: 成功響應
schema:
$ref: '#/definitions/ApiResponse'
get:
summary: 根據ID查詢城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
responses:
200:
description: 成功響應
schema:
$ref: '#/definitions/ApiCityResponse'
/city/search:
post:
summary: 根據條件查詢城市列表
parameters:
- name: body
in: body
description: 城市實體類
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功響應
schema:
$ref: '#/definitions/ApiCityListResponse'
/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'
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: 返回信息
ApiCityResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回碼
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/City'
CityList:
type: array
items:
$ref: '#/definitions/City'
ApiCityListResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回碼
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/CityList'
ApiCityPageResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回碼
message:
type: string
description: 返回信息
data:
properties:
total:
type: integer
format: int32
rows:
$ref: '#/definitions/CityList'
五.批量生成API文檔
使用<<黑馬程序員代碼生成器>>自動生成所有標的yml文檔,自動生成的文檔中類型均為string ，我們這里需要再對類型進行修改即可.
步驟：
（1）執行建表腳本
（2）使用《黑馬程序員代碼生成器》生成腳本(HeimaCodeUtil_V2.4_64.zip)
六.swaggerUI
SwaggerUI是用來展示Swagger文檔的界面，以下為安裝步驟
（1）在本地安裝nginx
（2）下載SwaggerUI源碼 https://swagger.io/download-swagger-ui/
（3）解壓，將dist文件夾下的全部文件拷貝至 nginx的html目錄
（4）啟動nginx
（5）瀏覽器打開頁面 http://localhost即可看到文檔頁面
（6）將編寫好的yml文件也拷貝至nginx的html目錄，這樣我們就可以加載我們的swagger文檔了
