1.天氣（JSON）
{"openapi": "3.1.0","info": {"title": "Get weather data","description": "Retrieves current weather data for a location.","version": "v1.0.0"},"servers": [{"url": "https://weather.example.com"}],"paths": {"/location": {"get": {"description": "Get temperature for a specific location","operationId": "GetCurrentWeather","parameters": [{"name": "location","in": "query","description": "The city and state to retrieve the weather for","required": true,"schema": {"type": "string"}}],"deprecated": false}}},"components": {"schemas": {}}}
這段代碼是一個OpenAPI規范的JSON文件，用于描述一個獲取天氣數據的API。總的來說，這個API允許用戶查詢特定位置的天氣數據。
-
"openapi": "3.1.0"：這表示使用的OpenAPI規范的版本是3.1.0。 -
"info"：這部分提供了API的基本信息，包括標題、描述和版本。 -
"servers"：這部分列出了API的服務器URL。 -
"paths"：這部分定義了API的路徑和操作。在這個例子中，有一個GET操作，路徑是/location，用于獲取特定位置的天氣。這個操作需要一個名為location的查詢參數，這個參數是必需的，類型是字符串。 -
"components"：這部分用于定義API中使用的模式，但在這個例子中，它是空的。
在OpenAPI規范中，parameters是一個數組，用于定義API操作的輸入參數。parameters定義了一個名為location的查詢參數，這個參數是必需的，類型是字符串。每個參數都是一個對象，包含以下屬性：
-
"name"：參數的名稱。 -
"in"：參數的位置。可以是"query","header","path"或"cookie"。 -
"description"：參數的描述。 -
"required"：如果為true，則此參數是必需的。 -
"schema"：參數的數據類型。
重點介紹下參數的位置，4種情況如下所示：
-
header參數，用于在請求頭中傳遞API密鑰。
-
path參數，用于在URL路徑中指定要檢索的對象的ID。
-
cookie參數，用于在cookie中傳遞用戶的會話ID。
-
query參數，附加在URL后面的參數，通常用于提供信息過濾。
創建自定義工具界面：
測試工具接口界面：
2.寵物商店（YAML）
# Taken from https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yamlopenapi: "3.0.0"info:version: 1.0.0title: Swagger Petstorelicense:name: MITservers:- url: https://petstore.swagger.io/v1paths:/pets:get:summary: List all petsoperationId: listPetstags:- petsparameters:- name: limitin: querydescription: How many items to return at one time (max 100)required: falseschema:type: integermaximum: 100format: int32responses:'200':description: A paged array of petsheaders:x-next:description: A link to the next page of responsesschema:type: stringcontent:application/json: schema:$ref: "#/components/schemas/Pets"default:description: unexpected errorcontent:application/json:schema:$ref: "#/components/schemas/Error"post:summary: Create a petoperationId: createPetstags:- petsresponses:'201':description: Null responsedefault:description: unexpected errorcontent:application/json:schema:$ref: "#/components/schemas/Error"/pets/{petId}:get:summary: Info for a specific petoperationId: showPetByIdtags:- petsparameters:- name: petIdin: pathrequired: truedescription: The id of the pet to retrieveschema:type: stringresponses:'200':description: Expected response to a valid requestcontent:application/json:schema:$ref: "#/components/schemas/Pet"default:description: unexpected errorcontent:application/json:schema:$ref: "#/components/schemas/Error"components:schemas:Pet:type: objectrequired:- id- nameproperties:id:type: integerformat: int64name:type: stringtag:type: stringPets:type: arraymaxItems: 100items:$ref: "#/components/schemas/Pet"Error:type: objectrequired:- code- messageproperties:code:type: integerformat: int32message:type: string
pet.yaml 是一個 OpenAPI 規范文件，用于描述和定義一個名為 “Swagger Petstore” 的 API 的接口。這個文件使用了 YAML 格式，它是一種用于編寫配置文件的人類可讀的數據序列化標準。這個文件為開發者提供了一個清晰的 API 接口定義，使得開發者可以知道如何與 “Swagger Petstore” API 進行交互。文件中的主要部分包括：
-
openapi: 這個字段指定了使用的 OpenAPI 規范的版本，這里是 “3.0.0”。 -
info: 這個部分提供了 API 的基本信息，包括版本、標題和許可證。 -
servers: 這個部分定義了 API 的服務器 URL。 -
paths: 這個部分定義了 API 的所有路徑和操作。例如，/pets路徑有兩個操作：get和post。get操作用于列出所有寵物，post操作用于創建一個新的寵物。每個操作都有自己的參數、響應和其他詳細信息。 -
components: 這個部分定義了可重用的模式（schemas），這些模式可以在paths部分中引用。例如，Pet、Pets和Error模式。
將上述YAML文件轉換為JSON格式：
{"openapi": "3.0.0","info": {"version": "1.0.0","title": "Swagger Petstore","license": {"name": "MIT"}},"servers": [{"url": "https://petstore.swagger.io/v1"}],"paths": {"/pets": {"get": {"summary": "List all pets","operationId": "listPets","tags": ["pets"],"parameters": [{"name": "limit","in": "query","description": "How many items to return at one time (max 100)","required": false,"schema": {"type": "integer","maximum": 100,"format": "int32"}}],"responses": {"200": {"description": "A paged array of pets","headers": {"x-next": {"description": "A link to the next page of responses","schema": {"type": "string"}}},"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Pets"}}}},"default": {"description": "unexpected error","content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}},"post": {"summary": "Create a pet","operationId": "createPets","tags": ["pets"],"responses": {"201": {"description": "Null response"},"default": {"description": "unexpected error","content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}},"/pets/{petId}": {"get": {"summary": "Info for a specific pet","operationId": "showPetById","tags": ["pets"],"parameters": [{"name": "petId","in": "path","required": true,"description": "The id of the pet to retrieve","schema": {"type": "string"}}],"responses": {"200": {"description": "Expected response to a valid request","content": {"application/json": {"schema": {"$ref": "#/components/schemas/Pet"}}}},"default": {"description": "unexpected error","content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}},"components": {"schemas": {"Pet": {"type": "object","required": ["id", "name"],"properties": {"id": {"type": "integer","format": "int64"},"name": {"type": "string"},"tag": {"type": "string"}}},"Pets": {"type": "array","maxItems": 100,"items": {"$ref": "#/components/schemas/Pet"}},"Error": {"type": "object","required": ["code", "message"],"properties": {"code": {"type": "integer","format": "int32"},"message": {"type": "string"}}}}}
}
3.空白模板
{"openapi": "3.1.0","info": {"title": "Untitled","description": "Your OpenAPI specification","version": "v1.0.0"},"servers": [{"url": ""}],"paths": {},"components": {"schemas": {}}}
注解：貌似JSON格式看上去更加直觀。
參考文獻
[1] OpenAPI Specification：https://swagger.io/specification/
