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

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 的現(xiàn)有用戶應(yīng)該非常熟悉此處描述的結(jié)構(gòu)。請注意，為了這篇文章的目的，我們已經(jīng)大大減少了示例中的消息結(jié)構(gòu)。源FHIR JSON Schema 文檔要全面得多。

添加溝通渠道

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

操作對象的刪除導(dǎo)致通道對象更加精簡并專注于技術(shù)實現(xiàn)。在我們的示例中，您可以看到 Channel 定義了一個address ，它是我們消息系統(tǒng)中假設(shè)的消息隊列，并通過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 版本中，通道對象更加關(guān)注技術(shù)實現(xiàn)。通道的重點允許 API 設(shè)計者將重點放在操作對象上，這種抽象提高了可重用性。

描述操作

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

我們創(chuàng)建了兩個操作對象， 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"

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

有效的 AsyncAPI 描述

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

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

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

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

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

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

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

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

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

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

簡化API縮寫：應(yīng)用程序編程接口終極指南

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

應(yīng)用程序開發(fā)蓬勃發(fā)展的必備開放API

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

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

優(yōu)化利潤：計算并報告OpenAI支持的API的COGS

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