openapi: 3.0.0
paths:
/tracking/{parcelId}/subscribe:
parameters:
- name: parcelId
in: path
required: true
description: The parcel identifier
schema:
$ref: '#/components/schemas/parcelId'
post:
summary: Subscribe to notifications about given parcel
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
url:
type: string
format: uri
token:
type: string
required:
- url
- token
responses:
202:
description: 'Successfully subscribed to notifications about given parcel'
content:
text/plain:
examples:
ok:
value: 'ok'
callbacks:
notification:
'{$request.body#/url}?token={$request.body#/token}':
post:
summary: 'Receive single notification about a parcel'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/notification'
responses:
200:
description: 'Notification successfully processed'
content:
text/plain:
examples:
ok:
value: 'ok'
components:
schemas:
parcelId:
type: string
pattern: '^[0-9]{16}$'
notification:
type: object
properties:
parcelId:
$ref: "#/components/schemas/parcelId"
status:
type: string
enum:
- pick-up
- in-transit
- delivered
required:
- parcelId
- status

好吧，等一下，內(nèi)容相當(dāng)多。讓我描述一下重要的幾行。

1.我們將POST在端點(diǎn)執(zhí)行請(qǐng)求/tracking/{parcelId}/subscribe，以便訂閱有關(guān) 所標(biāo)識(shí)的包裹的通知parcelId。

注意： $ref: '#/components/schemas/parcelId'這是一個(gè)技巧，使我們能夠重用parcelId模式定義（在文檔末尾的組件部分中定義）

2.請(qǐng)求主體部分定義預(yù)期的輸入負(fù)載：

注意： token 可能是隨機(jī)生成的數(shù)據(jù)（我們需要將其存儲(chǔ)在我們這邊）。它也可能是公鑰（那么我們只需要驗(yàn)證它是否與我們的秘密私鑰匹配）。

requestBody:

  required: true

  content:

    application/json:

      schema:

        type: object

        properties:

          url:

            type: string

            format: uri

          token:

            type: string

        required:

          - url

          - token

3.接下來，responses部分定義單個(gè)202響應(yīng)。202表示“接受”以供進(jìn)一步處理。

最重要的部分： 。在我們的例子中，keywordcallbacks下的鍵是它們的名稱。然后是標(biāo)題 – 。此路徑是運(yùn)行時(shí)表達(dá)式。路徑表示將從請(qǐng)求正文中提取并構(gòu)建通知接收 URL。callbacksnotification'{$request.body#/url}?token={$request.body#/token}'urltoken

客戶端服務(wù)的 OpenAPI 規(guī)范

client.oas3.yaml



openapi: 3.0.0

paths:

  /notify:

    post:

      summary: 'Receive notification about a parcel'

      security:

        - TokenSecurity: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/notification'

      responses:

        '200':

          description: 'Notification successfully processed'

          content:

            text/plain:

              examples:

                ok:

                  value: 'ok'

components:

  securitySchemes:

    TokenSecurty:

      type: apiKey

      name: token

      in: query

  schemas:

    parcelId:

      type: string

      pattern: '^[0-9]{16}$'

    notification:

      type: object

      properties:

        parcelId:

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

        status:

          type: string

          enum:

          - pick-up

          - in-transit

          - delivered

      required:

      - parcelId

      - status

我們的 API 規(guī)范定義了一個(gè)處理通知接收的端點(diǎn)。就這么簡單！

讓我們模擬

我們已經(jīng)定義了物流服務(wù) API 和我們的 API 的規(guī)范。現(xiàn)在是時(shí)候啟動(dòng)prism實(shí)例并查看一些操作了。

下面的命令將為港口prism的物流公司運(yùn)行實(shí)例4010。

prism mock -p 4010 logistics.oas3.yaml

現(xiàn)在請(qǐng)打開新的控制臺(tái)并運(yùn)行以下命令：

prism mock -p 4011 client.oas3.yaml

準(zhǔn)備好？

curl -v -H'Content-type: application/json' -d'{ "url": "http://localhost:4011/notify", "token": "dontpeek" }' http://127.0.0.1:4010/tracking/7352110771638879/subscribe

以下是物流服務(wù)的輸出：

[CLI] …  awaiting  Starting Prism…

[HTTP SERVER]   info      Server listening at http://127.0.0.1:4010

[CLI]   info      POST       http://127.0.0.1:4010/tracking/7352110771638879/subscribe

[HTTP SERVER] post /tracking/7352110771638879/subscribe   info      Request received

    [NEGOTIATOR]   info      Request contains an accept header: */*

    [VALIDATOR]   success   The request passed the validation rules. Looking for the best response

    [NEGOTIATOR]   success   Found a compatible content for */*

    [NEGOTIATOR]   success   Responding with the requested status code 202

    [CALLBACK]   info      notification: Making request to http://localhost:4011/notify?token=dontpeek...

    [CALLBACK]   info      notification: Request finished

以及客戶端服務(wù)控制臺(tái)相應(yīng)的輸出：

[CLI] …  awaiting  Starting Prism…

[HTTP SERVER]   info      Server listening at http://127.0.0.1:4011

[CLI]   info      POST       http://127.0.0.1:4011/notify

[HTTP SERVER] post /notify   info      Request received

    [NEGOTIATOR]   info      Request contains an accept header: */*

    [VALIDATOR]   success   The request passed the validation rules. Looking for the best response

    [NEGOTIATOR]   success   Found a compatible content for */*

    [NEGOTIATOR]   success   Responding with the requested status code 200

哇哦！發(fā)生什么事了？

  1. 請(qǐng)求POST已提出http://127.0.0.1:4010/tracking/7352110771638879/subscribe
  2. Prism 回復(fù)202表示訂閱已被接受。
  3. 請(qǐng)求體包含回調(diào)URL和token
  4. 回調(diào)定義包含有關(guān)如何構(gòu)造 WebHook URL 的配方，這將導(dǎo)致http://localhost:4011/notify?token=dontpeek
  5. 發(fā)生 Parcel 事件，觸發(fā)通知請(qǐng)求
  6. /notifyPrism使用模擬有效負(fù)載向我們的端點(diǎn)執(zhí)行請(qǐng)求
  7. 客戶端控制臺(tái)顯示已收到通知

對(duì)于那些喜歡圖表的人來說，這里有一個(gè)序列圖。它展示了訂閱回調(diào)和接收三個(gè)通知的過程。

序列圖

恭喜，您剛剛模擬了兩個(gè)服務(wù)并強(qiáng)制它們相互通信。本教程到此結(jié)束！

那很好，但是我為什么需要 Prism？

測(cè)試回調(diào)可能會(huì)變得很復(fù)雜。你可能需要編寫一些小工具來模擬調(diào)用者服務(wù)。或者用curl “手動(dòng)”調(diào)用它。或者強(qiáng)制服務(wù)調(diào)用你的 API 并相信它確實(shí)會(huì)這樣做。

聽起來還挺簡單的？現(xiàn)在想象一下你的 API 會(huì)隨著時(shí)間而改變。你需要維護(hù)該工具，但你丟失了curl命令，而且沒有關(guān)于如何快速測(cè)試 API 的文檔。哦，多么熟悉啊！

但是，等一下，您有一個(gè)始終保持最新的 OpenAPI 規(guī)范（因?yàn)槟睦习甯嬖V您這樣做），并且 Prism 可以將其變成 API 任何部分的功能齊全的模仿。現(xiàn)在您既不需要秘密命令，也不需要非文檔化的工具。

原文鏈接：Mocking?Callbacks?with?OpenAPI?and?Prism

上一篇：

Java API 最佳實(shí)踐

下一篇：

API版本控制與微服務(wù)：最佳實(shí)踐的重要性
#你可能也喜歡這些API文章!

我們有何不同？

API服務(wù)商零注冊(cè)

多API并行試用

數(shù)據(jù)驅(qū)動(dòng)選型，提升決策效率

查看全部API→
??

熱門場(chǎng)景實(shí)測(cè)，選對(duì)API

#AI文本生成大模型API

對(duì)比大模型API的內(nèi)容創(chuàng)意新穎性、情感共鳴力、商業(yè)轉(zhuǎn)化潛力

25個(gè)渠道
一鍵對(duì)比試用API 限時(shí)免費(fèi)

#AI深度推理大模型API

對(duì)比大模型API的邏輯推理準(zhǔn)確性、分析深度、可視化建議合理性

10個(gè)渠道
一鍵對(duì)比試用API 限時(shí)免費(fèi)