必要字段！Swagger規范版本，必須填2.0，否則該YAML將不能用於Swagger其他組件
swagger: '2.0'
必要字段！描述API接口信息的元數據
info:
接口標題
title: swagger說明文檔
接口文檔的描述
description: 學習Swagger
版本號
version: 1.0.0
Swagger會提供測試用例，host指定測試時的主機名，如果沒有指定就是當前主機,可以指定端口．
host: 127.0.0.1
定義的api的前綴，必須已/開頭,測試用例的主機則為:host＋bashPath
basePath: /api
指定調用接口的協議，必須是:"http", "https", "ws", "wss"．默認是http.-表示是個數組元素，即schemes接受一個數組參數
schemes:
- http
- https
對應與http協議頭request的Accept，調用者可接受類型,默認是/,定義的類型必須是http協議定義的 Mime Types,RestfulAPI一般定義成application/json
這兩個是對所有接口的全局設置，在細化的接口中是還可以對應這兩個屬性來覆蓋全局屬性
produces:
- application/json
必要字段!定義可有可操作的API
paths:
/users:
必要字段!定義HTTP操作方法，必須是http協議定義的方法
get:
#接口概要
summary: 查詢所有用戶信息
#接口描述
description: 查詢出所有用戶的所有信息，用戶名，別名
#標簽，方便快速過濾出User相關的接口
tags:
- User
#返回值描述，必要自動
responses:
#返回的http狀態碼
200:
description: 所有用戶信息或者用戶的集合信息
#描述返回值
schema:
#返回值格式，可選的有array,integer,string,boolean
type: array
#針對array,每個條目的格式,type定義為array．必要填寫items
items:
#引用在definitions下定義的Users
$ref: '#/definitions/User'
#執行出錯的處理
default:
description: 操作異常,執行失敗.返回信息描述錯誤詳情
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
message:
#類型
type: string
#即對於同一個url定義兩個不同的方法，表示兩個接口
post:
description: 注冊一個用戶
#請求參數
parameters:
#參數key
- name: username
#傳遞方法，formData表示表單傳輸，還有query表示url拼接傳輸，path表示作為url的一部分
#body表示http頭承載參數(body只能有一個,有body不能在有其他的)
in: formData
#參數描述
description: 用戶名，不能使用已經被注冊過的
#參數是否必要，默認false
required: true
#參數類型，可選的包括array,integer,boolean,string.使用array必須使用items
type: string
- name: password
in: formData
description: 用戶登陸密碼，加密傳輸，加密存儲
required: true
type: string
- name: alias
in: formData
type: string
description: 用戶別名
#非必要字段
required: false
responses:
#返回的http狀態碼
200:
description: 通過返回值來標示執行結果 返回true表示執行成功
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
status:
#類型
type: boolean
#描述
description: 是否成功
#執行出錯的處理
default:
description: 操作異常,執行失敗.返回信息描述錯誤詳情
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
message:
#類型
type: string
/users/{id}:
#{id}表示id為請求參數，例如/users/1,/users/2都是對該API的請求，此時id即為１和2
get:
summary: 根據用戶名id查詢該用戶的所有信息
description: 查詢出某個用戶的所有信息，用戶名，別名等
tags:
- User
parameters:
#上面接口中定義了{id}，則參數列表中必須包含參數id,並且請求類型為path
- name: id
in: path
description: 要查詢的用戶的用戶名,它是唯一標識
required: true
type: string
responses:
200:
description: 所有用戶信息或者用戶的集合信息
schema:
$ref: '#/definitions/User'
default:
description: 操作異常,執行失敗.返回信息描述錯誤詳情
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
message:
#類型
type: string
#http定義的delete方法,刪除一個資源
delete:
summary: 刪除用戶
description: 刪除某個用戶的信息，被刪除的用戶將無法登陸
parameters:
- name: id
in: path
type: string
required: true
description: 用戶的唯一標示符
tags:
- User
responses:
200:
description: 通過返回值來標示執行結果 返回true表示執行成功
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
status:
#類型
type: boolean
#描述
description: 是否成功
default:
description: 操作異常,執行失敗.返回信息描述錯誤詳情
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
message:
#類型
type: string
#描述錯誤信息
#http定義的patch方法，表示修改一個資源
patch:
summary: 用戶信息修改
description: 修改用戶信息(用戶名別名)
parameters:
- name: id
in: path
description: 用戶名,要修改的數據的唯一標識符
required: true
type: string
- name: alias
in: formData
description: 新的用戶別名
required: true
type: string
tags:
- User
responses:
200:
description: 通過返回值來標示執行結果 返回true表示執行成功
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
status:
#類型
type: boolean
#描述
description: 是否成功
default:
description: 操作異常,執行失敗.返回信息描述錯誤詳情
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
message:
#類型
type: string
#描述錯誤信息
definitions:
User:
#值類型
type: object
#定義屬性
properties:
#屬性名
id:
#類型
type: string
#描述
description: 用戶的唯一id
username:
type: string
description: 用戶名
alias:
type: string
description: 別名
————————————————
版權聲明：本文為CSDN博主「u010466329」的原創文章，遵循CC 4.0 BY-SA版權協議，轉載請附上原文出處鏈接及本聲明。
原文鏈接：https://blog.csdn.net/u010466329/article/details/78522992