大模型RAG技術：從入門到實踐
Info 對象是OpenAPI文檔的頭部信息部分，它包含了API的標題、描述、版本號等信息。這些信息對用戶了解API的用途和版本至關重要。以下是Info對象的一個示例：
info:
title: OpenAPI 教程
description: "這是一個用于教學的API程序"
version: '1.1'
termsOfService: "https://openweathermap.org/terms"
contact:
name: "API 開發者"
url: "http://myblog.cn"
email: "youemai@gmail.com"
license:
name: "Apache 2.0"
url: "http://springdoc.org"
Servers 對象定義了API的服務器信息，即API可以被訪問的URL。它支持多服務器配置，便于在開發、測試和生產環境中使用不同的服務器。
servers:
- url: 'http://localhost:8080/webapi'在這個例子中，指定了一個本地服務器的URL，用戶可以根據需要切換不同的服務器環境。
servers:
- url: https://localhost:8080/webapi
description: 開發服務器
- url: http://test-server:8080/webapi
description: 測試服務器
- url: http://product-server:8080/webapi
description: 生產服務器這種配置方式允許用戶在不同環境中靈活選擇不同的服務器，方便API的開發和測試。
Paths對象是OpenAPI文檔的核心部分，它定義了API的各個路徑及其相關的操作。每個路徑可以包含多個操作方法，例如GET、POST、PUT、DELETE等。
paths:
/pet:
get:在這個例子中，定義了一個名為/pet的路徑，并為其配置了一個GET方法。
Operation對象描述了每個路徑的具體操作，包括請求參數、響應格式等。以下是一個完整的Operation對象示例：
paths:
/weather:
get:
tags:
- 天氣數據
summary: "獲取一個地點的實時天氣數據。"
description: "^_^"
operationId: CurrentWeatherData
parameters:
- name: q
in: query
description: "查詢城市名稱。"
schema:
type: string在這個示例中，定義了一個用于獲取天氣數據的GET方法，并為其配置了查詢參數q。
Components對象是OpenAPI 3.0中新增的功能，它用于定義可重用的對象，減少冗余。通過在Components中定義公共的參數和響應對象，可以在多個路徑中重復使用。
components:
parameters:
q:
name: q
in: query
description: "城市名稱"
schema:
type: string然后在Paths中引用它：
paths:
/weather:
get:
parameters:
- $ref: '#/components/parameters/q'這種方式既提高了文檔的可維護性，也減少了代碼的冗余。
responses:
200:
description: 成功響應
content:
application/json:
schema:
$ref: '#/components/schemas/200'通過引用已經定義的響應對象，可以保持文檔結構的一致性。
Security對象用于定義API的安全認證方式。OpenAPI 3.0支持多種認證方式，包括API Key、HTTP、OAuth 2.0和OpenID Connect。
security:
- app_id: []在Components中詳細描述API Key的使用：
components:
securitySchemes:
app_id:
type: apiKey
description: API key用于授權請求。
name: appid
in: query通過這種方式，用戶可以在請求API時，提供必要的認證信息。
Tags對象用于對API路徑進行分組管理，使用戶可以更方便地瀏覽API。以下是Tags對象的示例：
paths:
/pets:
get:
summary: 列出所有寵物
operationId: listPets
tags:
- pets在根目錄級別添加Tags屬性，描述分組信息：
tags:
- name: pets
description: "動物歡樂世界"通過這種方式，用戶可以快速了解每個分組的功能和作用。
ExternalDocs對象允許API文檔引用外部資源，提供額外的信息支持。這在需要補充說明時非常有用。
externalDocs:
description: 外部API文檔
url: https://openweathermap.org/api這種鏈接可以為用戶提供更多的背景和參考信息，增強文檔的實用性。
OpenAPI 3.0 規范提供了一種結構化的方法來定義和描述API，使開發者能夠更高效地開發、測試和維護API。在本文中，我們詳細介紹了OpenAPI 3.0的各個對象及其使用方法，幫助您全面理解和應用這一強大的工具。
問：OpenAPI 3.0是什么？
問：如何在OpenAPI中定義多個服務器？
問：什么是Components對象？
問：如何使用API Key進行認證？
問：如何在OpenAPI中使用外部文檔？
