架構對象遵循與 AsyncAPI 版本 2.x 和 OpenAPI 基本相同的語義。在我們的示例中，這些在組件對象中實現，以便跨消息對象重用。我們總共創建了四個，具有兩個操作的請求和響應有效負載，然后實現了引用每個操作的消息對象，并且可以攜帶消息的語義，包括公共標頭等消息特征。我們實現了一個 header?health-system-id?，它提供了發送消息的系統的高級指示器。

components:

  messages:

    patientMedicationStatementRequest:

      summary: Request message for patient and current medication data

      title: Patient and Medication Request

      payload:

        $ref: "#/components/schemas/patientMedicationStatementRequestPayload"

      traits:

        - $ref: "#/components/messageTraits/healthSystemHeaders"

    patientMedicationStatementResponse:

      summary: Response message for patient and current medication data

      title: Patient and Medication Response

      payload:

        $ref: "#/components/schemas/patientMedicationStatementRequestPayload"

      traits:

        - $ref: "#/components/messageTraits/healthSystemHeaders"

    patientMedicationRequest:

      summary: Request message for patient and current medication data

      title: Patient and Medication Request

      payload:

        $ref: "#/components/schemas/patientMedicationStatementRequestPayload"

      traits:

        - $ref: "#/components/messageTraits/healthSystemHeaders"

    patientMedicationResponse:

      summary: Request message for patient and current medication data

      title: Patient and Medication Request

      payload:

        $ref: "#/components/schemas/patientMedicationStatementRequestPayload"

      traits:

        - $ref: "#/components/messageTraits/healthSystemHeaders"

  schemas:

    patientMedicationStatementRequestPayload:

      type: "object"



      # Remainder of Schema Object definitions



  messageTraits:

    healthSystemHeaders:

      headers:

        type: object

        properties:

          health-system-id:

            description: Health system provider ID as UUID

            type: string

            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

因此，AsyncAPI 的現有用戶應該非常熟悉此處描述的結構。請注意，為了這篇文章的目的，我們已經大大減少了示例中的消息結構。源FHIR JSON Schema 文檔要全面得多。

添加溝通渠道

消息就位后，我們創建了Channel 對象。通道描述了發送和接收消息的傳輸機制，并將給定的消息隊列或主題與其支持的消息結構對齊。 3.0 版中對 Channel 對象的更改值得注意，因為publish和subscribe屬性已被刪除，并且它們引用的操作對象已移至其自己的根級屬性。

操作對象的刪除導致通道對象更加精簡并專注于技術實現。在我們的示例中，您可以看到 Channel 定義了一個address ，它是我們消息系統中假設的消息隊列，并通過messages屬性提供支持的消息和通道之間的綁定：

channels:

  patientMedicationStatements:

    description: Channel for requesting patient record and medication statement

    address: health.patient.medication.statement

    messages:

      patientMedicationStatementRequest:

        $ref: "#/components/messages/patientMedicationStatementRequest"

      patientMedicationStatementResponse:

        $ref: "#/components/messages/patientMedicationStatementResponse"

  patientMedicationRequest:

    description: Channel for ordering medication for a patient

    address: health.patient.medication.request

    messages:

      patientMedicationRequest:

        $ref: "#/components/messages/patientMedicationRequest"

      patientMedicationResponse:

        $ref: "#/components/messages/patientMedicationResponse"

在 3.0 版本中，通道對象更加關注技術實現。通道的重點允許 API 設計者將重點放在操作對象上，這種抽象提高了可重用性。

描述操作

我們設計的最后一步是創建操作對象，它使我們能夠告訴 AsyncAPI 描述的使用者“做什么”以將他們的應用程序與我們的 API 集成。由于操作對象的名稱是給定對象的標識符，因此我們決定使用標準前綴order-medication/來命名它們，以提供對操作進行分組的方法。我們可以使用標簽對象作為此方法的替代方案。

我們創建了兩個操作對象， order-medication/get-patient-and-medication-statement 和 order-medication/make-medication-request 映射到我們的藥物訂購用例中的兩個操作：

operations:

  order-medication/get-patient-and-medication-statement:

    summary: Retrieve the patient record and current medication for the patient

    action: send

    channel:

      $ref: "#/channels/patientMedicationStatements"

    messages:

      - $ref: "#/channels/patientMedicationStatements/messages/patientMedicationStatementRequest"

    reply:

      address:

        "location": "$message.header#/replyTo"

      channel:

        $ref: "#/channels/patientMedicationRequest"

      messages:

        - $ref: "#/channels/patientMedicationRequest/messages/patientMedicationResponse"

  order-medication/make-medication-request:

    summary: Send a medication request on-behalf of the patient

    action: send

    channel:

      $ref: "#/channels/patientMedicationRequest"

    messages:

      - $ref: "#/channels/patientMedicationRequest/messages/patientMedicationRequest"

    reply:

      address:

        "location": "$message.header#/replyTo"

      channel:

        $ref: "#/channels/patientMedicationRequest"

      messages:

        - $ref: "#/channels/patientMedicationRequest/messages/patientMedicationResponse"

操作引用我們已經創建的通道對象及其支持的消息。我們還在操作中利用了 3.0 版本的另一個新功能，操作回復對象。操作回復對象支持請求/回復模式的實現，這是一種非常常見的消息傳遞范例。在我們的示例中，我們指定了一個動態設置的回復隊列，它是使用運行時表達式指定的。回復的系統在發送響應時必須使用消息頭replyTo的值。

有效的 AsyncAPI 描述

將 3.0 版 AsyncAPI 描述集中在一起，重點關注特定用例，顯示了 AsyncAPI 規范修訂后的結構的一些重要內容，即： 添加操作對象提供了消息、傳輸和操作描述之間的關注點分離。

除了能夠描述用例之外，修訂后的結構還有其他幾個顯著的好處：

• 一致性：操作對象可以在整個 API 生命周期中在 AsyncAPI 文檔中保持靜態，從而提供一致的簽名。因此，操作對象更容易管理，因為它們不會“陷入”傳輸語義中。
• 可移植性：將操作對象與通道對象分離意味著通道對象可以描述一次然后重復使用，包括跨 AsyncAPI 描述。這使得通道對象更加可移植。
• 所有權：不同團隊擁有其負責的 AsyncAPI 描述部分的所有權的方式補充了一致性和可移植性。例如，技術運營團隊可以向 API 設計團隊單獨定義通道對象，并在信息可用時注入通道定義，例如服務器對象。這使得組織能夠采用管道方法來創建準確的 AsyncAPI 描述，并利用自動化來確保描述盡可能準確。

我們將設計重點放在“自下而上”的方法上，使用源自開放標準的現有消息有效負載結構，并創建我們的操作對象作為最后一步。當然，您可以按照自己的方法來構建 AsyncAPI 描述（這完全取決于您），但是用例設計方法為您希望界面實際執行的操作提供了一些切實的結果。如果您愿意，您可以首先從操作對象開始，勾勒出支持的操作的要求并與設計利益相關者達成一致，然后再開始詳細的消息傳遞設計。

在 AsyncAPI 中描述用例的主要缺點是傳達順序和依賴關系。除了通過描述和命名約定之外，AsyncAPI 不通過操作對象傳達此信息。然而，提供全功能用例描述的下一步將通過 OpenAPI Initiative?Arazzo規范來提供。支持 AsyncAPI 最初是在 1.0.0 版本中發布的，現在又出現在下一版本的路線圖中。

Arazzo 將提供更豐富的方法來描述端到端用例，包括依賴關系、操作之間傳遞的動態值以及基于消息數據的故障條件。這與解耦的操作對象一起，使得通過異步 API的豐富用例描述來改善開發人員體驗變得非常可行。

原文鏈接：https://nordicapis.com/how-to-write-a-v3-asyncapi-description/

#你可能也喜歡這些API文章!

掌握API建模：基本概念和實踐

程序員常用的API接口管理工具有哪些？

簡化API縮寫：應用程序編程接口終極指南

如何為你的項目挑選最佳API？完整選擇流程解讀

應用程序開發蓬勃發展的必備開放API

.NET Core Web APi類庫如何內嵌運行和.NET Core Web API 中的異常處理

.NET Core Web API + Vue By Linux and Windows 部署方案知識點總結

優化利潤：計算并報告OpenAI支持的API的COGS

用于集成大型語言模型的LLM API