[ADP-57] API 規格可發現性

指引

• 為了提高可發現性和改善開發者體驗，所有生產環境 API 都應該（SHOULD）提供 API 規格的位置。
• 可以（MAY）在向 API 伺服器根路徑發送 GET 請求時，透過標準 Link 標頭在 API 伺服器中提供 API 規格位置。
• 應該（SHOULD）使用 service-desc 或 describedby 關聯類型。
• 應該（SHOULD）在 Link 標頭中包含內容類型資訊，以指示 API 規格的格式。
• 必須（MUST）確保 API 規格 URL 可以訪問，並在需要時提供適當的身份驗證。

TIP

describedby 是由 POWDER 透過 RFC 5988 在 IANA Link Relation Registry 中註冊的，而 service-desc 則是由 RFC 8631 註冊的。這兩種語義都適合用於描述 API 規格位置。

實作細節

內容類型

• 提供 API 規格時，應該（SHOULD）支援以下內容類型：
  • application/openapi+json;version=3.0 - 用於 JSON 格式的 OpenAPI 3.0
  • application/openapi+yaml;version=3.0 - 用於 YAML 格式的 OpenAPI 3.0
  • application/vnd.oai.openapi+json;version=3.1 - 用於 JSON 格式的 OpenAPI 3.1
  • application/vnd.oai.openapi+yaml;version=3.1 - 用於 YAML 格式的 OpenAPI 3.1
  • application/vnd.aai.asyncapi+json;version=2.0 - 用於 JSON 格式的 AsyncAPI 2.0
  • application/vnd.aai.asyncapi+yaml;version=2.0 - 用於 YAML 格式的 AsyncAPI 2.0
  • application/vnd.aai.asyncapi+json;version=2.6 - 用於 JSON 格式的 AsyncAPI 2.6
  • application/vnd.aai.asyncapi+yaml;version=2.6 - 用於 YAML 格式的 AsyncAPI 2.6

多種規格

如果有多種 API 規格格式可用，可以（MAY）提供多個 Link 標頭：

Link: <https://api.example.com/openapi.json>; rel="service-desc"; type="application/openapi+json;version=3.0"
Link: <https://api.example.com/openapi.yaml>; rel="service-desc"; type="application/openapi+yaml;version=3.0"

提供文件網站

要提供規格文件網站，可以（MAY）提供以下 Link 標頭：

Link: <https://api.example.com/docs>; rel="service-doc"

設計思考

這個設計受到這裡的討論和這個文件的啟發。

這個設計目的是在提高 API 文件的可發現性。當然，我們可以在使用者代理發出第一個請求之前提供 API 文件位置；然而，發現 API 伺服器的代理可以利用 Link 標頭自行找到 API 文件位置。我認為這實現了 HATEOAS（Hypermedia as the Engine of Application State，超媒體作為應用程式狀態引擎）的一種形式，允許客戶端動態發現 API 功能。

使用標準 Link 標頭提供了一種一致的、機器可讀的方式來發現不同服務的 API 規格，使工具能夠自動找到並使用這些規格進行測試、程式碼生成或文件目的。

範例

基本範例

請求：

GET / HTTP/1.1
Host: api.example.com

回應：

HTTP/1.1 200 OK
Link: <https://api.example.com/openapi.json>; rel="service-desc"; type="application/openapi+json;version=3.0"

綜合範例

請求：

GET / HTTP/1.1
Host: api.example.com

回應：

HTTP/1.1 200 OK
Link: <https://api.example.com/openapi.json>; rel="service-desc"; type="application/openapi+json;version=3.0"
Link: <https://docs.example.com>; rel="service-doc"

參考資料

• RFC 8288 - Web 連結
• RFC 5988 - Web 連結
• RFC 8631 - Web 服務的連結關係類型
• IANA Link Relation Registry
• Mapping OpenAPI to the CLI
• POWDER - Web 描述資源協議
• OpenAPI 規格