Resuful
Resuful是一種開發思想，是一種網絡應用程序的設計風格和開發方式，基於http,可以使用xml或者json格式定義。具體可以查看Resuful的百度百科。
總結起來的話就是：
- 每一個URI代表一種資源
- 客戶端和服務器之間，傳遞這種資源的某種表現層
- 客戶端通過http的幾種請求方式，對服務器資源進行操作，實現“表現層狀態轉化”
請求的URI是不應該包含動詞的，動詞完全由get、post、delete、put、patch等方法進行表現
下面進行講解幾種方法
get：獲取數據，信息存儲在url中，不安全，無法傳遞太大的數據
head：head就像get，只不過服務器接受到head請求後只返回響應頭，而不會發送響應內容。當我們只需要查看某個頁面的狀態的時候，使用head是非常高效的，因爲在傳輸的過程中省去了頁面內容
post:一般用於表單的提交數據。數據包含在請求體中
put:從客戶端向服務器傳送的數據取代執行的文檔的內容
patch：實體中包含一個表，表中說明與該URI所表示的原內容的區別。
delete:請求服務器刪除指定的頁面
put、post、patch的區別：
一般簡單的會聽到這樣的話：post是新增，put是修改整個資源，patch是修改局部資源。那麼最基礎的區別是什麼呢？
post和put的區別：
post請求的URI表示處理該封閉實體的資源，該資源可能是個數據接收過程。某種協議的網關或接收註解的獨立實體。然而put中的URI表示請求中封閉的實體–用戶代理知道URI的目標，並且服務器無法將請求應用到其他資源。如果服務器希望該請求應用到另一個URI，就必須發送一個301響應，用戶代理可以通過自己的判斷來決定是否轉發該請求。
post不是冪等、put是冪等
put和patch都可以進行更新資源，但是如果頁面只能進行更新一個字段，而不是整個整體，那麼就需要用到patch，可以減少帶寬的使用。put是用來更新整體的。
OpenApi
openApi就是開放api。也就是網站的一些服務商將自己的網站服務封裝成一系列的api開放出去，供第三方開發者使用。
ApI文檔應該是構建應用程序的基礎，這個原則正是API-First開發的全部內容。現在流行的前後端分離的開發思想，那麼在設計完接口之後，前後端都可以同時開發。
那麼如何編寫openApi呢？Resuful思想是基礎，在此基礎上展示出你的接口。簡單的可以理解爲一種格式：可用json和yaml兩種形式展示。最終展示爲網頁的形式：
我這個是將代碼上傳至GitLab上之後，打開文檔會直接被渲染成網頁的形式。當然也有一些軟件用於展示頁面：如swagger工具。
openApi文檔的三個必需的部分或對象：
1、openapi----openApi規範版本的語義版本號
2、info----有關api的元數據
3、paths–api的可用路徑和操作
openapi對象聲明瞭用於文檔的規範的版本。該版本對於用戶理解文檔的結構至關重要，更重要的是，對於可能爲了驗證目的而獲取文檔或創建虛擬服務的任何工具，info對象提供有關API本身的基本信息。標題和版本是必填字段，我們可以選擇包含其他信息，例如說明，聯繫和許可信息。
具體可以查看openApi的官方文檔：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md
以下是我寫的例子：僅供參考
openapi_userApi.yaml
openapi: 3.0.0
info:
title: "HttpServer的Api接口"
version: "1.0.0"
contact:
name: ZhouZhou
email: [email protected]
tags:
- name: usersApi
description: user 用戶
paths:
/api/users/login:
post:
summary: 登錄
tags: ["usersApi"]
requestBody:
required: true
content:
application/json:
schema:
$ref: "userApiRequest.yaml#/user/schemas/userLogin"
responses:
"200":
description: 操作成功
content:
application/json:
schema:
$ref: "userApiReturn.yaml#/user/schemas/userLogin"
default:
description: 意外出錯
content:
application/json:
schema:
$ref: "defaultError.yaml#/error/schemas/errorMsg"
/api/users:
post:
summary: 用戶註冊
tags: ["usersApi"]
requestBody:
required: true
content:
application/json:
schema:
$ref: "userApiRequest.yaml#/user/schemas/userObject"
responses:
"200":
description: 操作成功
content:
application/json:
schema:
$ref: "userApiReturn.yaml#/user/schemas/userRegister"
default:
description: 意外出錯
content:
application/json:
schema:
$ref: "defaultError.yaml#/error/schemas/errorMsg"
get:
description: 返回所有用戶列表
summary: 返回用戶列表
tags: ["usersApi"]
responses:
"200":
description: 操作成功
content:
application/json:
schema:
type: array
items:
$ref: "userApiReturn.yaml#/user/schemas/userObject"
default:
description: 意外出錯
content:
application/json:
schema:
$ref: "defaultError.yaml#/error/schemas/errorMsg"
/api/users/{id}:
get:
summary: 根據用戶ID查詢用戶信息
tags: ["usersApi"]
parameters:
- name: id
in: path
description: URL路徑參數,用戶ID
required: true
schema:
type: string
example: 921921
responses:
"200":
description: 操作成功
content:
application/json:
schema:
$ref: "userApiReturn.yaml#/user/schemas/userObject"
default:
description: 意外出錯
content:
application/json:
schema:
$ref: "defaultError.yaml#/error/schemas/errorMsg"
delete:
summary: 根據用戶ID刪除用戶信息
tags: ["usersApi"]
parameters:
- name: id
in: path
description: URL路徑參數,用戶ID
required: true
schema:
type: string
example: 921921
responses:
"200":
description: 操作成功
content:
application/json:
schema:
$ref: "userApiReturn.yaml#/user/schemas/oprCount"
default:
description: 意外出錯
content:
application/json:
schema:
$ref: "defaultError.yaml#/error/schemas/errorMsg"
patch:
summary: 根據用戶ID修改用戶信息
tags: ["usersApi"]
parameters:
- name: id
in: path
description: URL路徑參數,用戶ID
required: true
schema:
type: string
example: 921921
requestBody:
required: true
content:
application/json:
schema:
$ref: "userApiRequest.yaml#/user/schemas/userObject"
responses:
"200":
description: 操作成功
content:
application/json:
schema:
$ref: "userApiReturn.yaml#/user/schemas/userRegister"
default:
description: 意外出錯
content:
application/json:
schema:
$ref: "defaultError.yaml#/error/schemas/errorMsg"
components:
securitySchemes:
api_Key:
type: apiKey
name: api_Key
in: header
以下是openapi_userApi.yaml引用的文檔：
defaultError.yaml
error:
schemas:
errorMsg:
type: object
properties:
error:
type: object
properties:
code:
type: integer
example: 0
message:
type: string
statusCode:
type: integer
example: 0
name:
type: string
userApiRequest.yaml
user:
schemas:
userLogin:
type: object
properties:
login_name:
type: string
example: admin
password:
type: string
example: admin1
required:
- login_name
- password
userObject:
type: object
properties:
login_name:
type: string
example: admin
user_name:
type: string
example: 週週
user_mobile:
type: string
example: 18137748494
user_email:
type: string
format: email
example: [email protected]
user_address:
type: string
example: 上海市閔行區
password:
type: string
format: password
example: admin1
required:
- login_name
- user_name
- user_mobile
- password
userList:
type: object
properties:
user_name:
type: string
example: 週週
user_mobile:
type: string
example: 18137748494
userApiReturn.yaml
user:
schemas:
userLogin:
type: object
properties:
login_name:
type: string
id:
type: string
required:
- login_name
- id
userRegister:
type: object
properties:
id:
type: string
login_name:
type: string
example: admin
password:
type: string
format: password
user_name:
type: string
example: 週週
user_mobile:
type: string
example: 18137748494
user_email:
type: string
format: email
example: [email protected]
user_address:
type: string
example: 上海市閔行區
required:
- id
- login_name
- user_name
- user_mobile
userObject:
type: object
properties:
id:
type: string
format: UUID
login_name:
type: string
user_name:
type: string
user_mobile:
type: string
user_email:
type: string
format: email
user_address:
type: string
oprCount:
type: object
properties:
count:
type: integer
format: int32
example: 0