Swagger Api Document Example (1.0.0)

Download OpenAPI specification:Download

這是一個學習如何使用 Swagger 產生 API Document 的範例。

learnRequest

在這個分類學習如何描述 Request

如何描述在 body 或 header 的參數

header Parameters

authorization

string

Example: "acde1jflk34fd21ekfkf"

參數在 header 中的例子，此處以 authorization 為例

Request Body schema: application/json

propString	string 這是一個字串的參數
propInt	int 這是一個整數的參數
propBoolean	boolean 這是一個布林值的參數
propArray	Array of any 這是一個陣列的參數
propObject	object 這是一個物件的參數

Responses

default

Default response

post /haveSomeParams

http://localhost/haveSomeParams

https://localhost/haveSomeParams

Request samples

Payload

application/json

Copy

Expand all Collapse all

{

"propString": "abcd",
"propInt": 123,
"propBoolean": false,
"propArray":
[
- 1,
- 2,
- 3
],
"propObject":
{
- "prop1": 1234,
- "prop2": "abcde",
- "prop3": true
}

}

如何描述在 query 中的參數

query Parameters

someQuery

required

string

Example: "yolo!"

參數在 query 中的例子

Responses

default

Default response

get /haveSomeParams/{someQuery}

http://localhost/haveSomeParams/{someQuery}

https://localhost/haveSomeParams/{someQuery}

learnResponse

在這個分類學習如何描述 Response

如何描述不同的 Response

Responses

200

這是一個成功 Response 的例子

400

缺少參數或參數格式不正確

401

帳號或密碼錯誤

get /haveSomeResponse

http://localhost/haveSomeResponse

https://localhost/haveSomeResponse

Response samples

application/json

Copy

Expand all Collapse all

{

"msg": "success",
"logCode": 2357

}

learnDefinition

在這個分類學習如何重複使用 Definition

如何使用 definition 在 Schema 層級描述 Response

definition 是可以重複使用的物件簡寫，可以用 "$ref" : "#/definitions/modelName" 存取

Responses

200

這是一個成功 Response 的例子

400

缺少參數或參數格式不正確

401

帳號或密碼錯誤

get /haveSomeResponse/withDefinition

http://localhost/haveSomeResponse/withDefinition

https://localhost/haveSomeResponse/withDefinition

Response samples

application/json

Copy

Expand all Collapse all

{

"msg": "success",
"logCode": 2357

}

如何使用 definition 在 Param 層級描述 Request

definition 可以描述各種層級，也可以直接在參數層級定義 definition

Request Body schema: application/json

propString	string 這是一個字串的參數
propInt	int 這是一個整數的參數
propBoolean	boolean 這是一個布林值的參數
propArray	Array of any 這是一個陣列的參數
propObject	object 這是一個物件的參數

Responses

default

Default response

post /haveSomeParams/withDefinition

http://localhost/haveSomeParams/withDefinition

https://localhost/haveSomeParams/withDefinition

Request samples

Payload

application/json

Copy

Expand all Collapse all

{

"propString": "abcd",
"propInt": 123,
"propBoolean": false,
"propArray":
[
- 1,
- 2,
- 3
],
"propObject":
{
- "prop1": 1234,
- "prop2": "abcde",
- "prop3": true
}

}

learnOthers

在這個分類學習如何描述 Request

可以在分類上放外部連結：