可以說，在前面的幾篇文章中恕曲，我們已經(jīng)對自行車在線商城的 REST API 進行了詳細(xì)的設(shè)計（通過圖和表格）灼捂。從今天開始，我們要使用 Open API 規(guī)范咏雌，對已有的 REST API 設(shè)計進行描述凡怎，朝著最終的開發(fā)實現(xiàn)，再邁進一步赊抖。

如果想了解和回顧 Open API 的基礎(chǔ)知識统倒，可以參考下面的文章：

• API 入門 (4) OpenAPI 文檔結(jié)構(gòu)
• API 入門 (5) OpenAPI 的 Paths 對象
• API 入門 (6) OpenAPI 響應(yīng)內(nèi)容
• API 入門 (7) OpenAPI 參數(shù)和載荷
• API 入門 (8) OpenAPI 組件對象
• API 入門 (9) OpenAPI 文檔字段和示例
• API 入門 (10) OpenAPI 服務(wù)器

如果想了解 Open API 環(huán)境的搭建，請參考下面的文章：

• API 入門 (11) OpenAPI 實戰(zhàn)——開發(fā)環(huán)境

本文先對 REST API 的資源和操作進行描述氛雪。

創(chuàng)建文檔

首先房匆，我們創(chuàng)建一個空白的 Open API 文檔，并修改自動產(chǎn)生的標(biāo)題詳細(xì)。

openapi: ‘3.0.2’
info:
  title: 自行車在線商城 REST API 文檔浴鸿。
  version: ‘1.0’
servers:
  - url: https://api.server.test/v1
paths:
  /test:
    get:
      responses:
        ‘200’:
          description: OK

接下來井氢，我們以目錄資源為例，對資源和操作進行描述岳链。

把設(shè)計轉(zhuǎn)成描述

描述資源

在 REST API 的設(shè)計中花竞，我們已經(jīng)識別出目錄資源，并用 /bikes 表示資源的路徑〉а疲現(xiàn)在通過文檔進行描述约急。

openapi: ‘3.0.2’
info:
  title: 自行車在線商城 REST API 文檔。
  version: ‘1.0’
servers:
  - url: https://api.server.test/v1
paths:  # 1
  /bikes: # 2
    description: 自行車目錄 # 3

在 YAML 格式中举户，可以使用 # 添加注釋，這也是 YAML 優(yōu)于 JSON 的一個地方遍烦。

# 1俭嘁，paths：表示資源的集合，所有資源都要放到這里服猪。
# 2供填，/bikes：表示目錄資源的路徑。
# 3罢猪，description：對資源的額外描述近她。不強制，但推薦膳帕，很有用粘捎。

描述操作

在 Open API 文檔中，資源必須包含相應(yīng)的操作危彩，否則文檔是無效的≡苣ィ現(xiàn)在我們來添加查詢操作。

openapi: ‘3.0.2’
info:
  title: 自行車在線商城 REST API 文檔汤徽。
  version: ‘1.0’
servers:
  - url: https://api.server.test/v1
paths:
  /bikes:
    description: 自行車目錄
    get: # 1 
      summary: 查詢自行車目錄 # 2
      description: |  # 3
        在自行車目錄中娩缰，使用關(guān)鍵詞，
        查詢匹配條件的自行車谒府。

# 1拼坎，get：get 屬性對應(yīng)的是 HTTP 的 GET 方法。
# 2完疫，summary：表示操作的簡短描述泰鸡。
# 3，description：表示對操作的詳細(xì)描述壳鹤。

還記得 | 這個符號嗎鸟顺？在這里可以找到答案。

這時候，文檔會提示一個警告：Missing property "responses".讯嫂。我們必須需要為操作添加一個響應(yīng)蹦锋，滿足文檔的有效性。

openapi: ‘3.0.2’
info:
  title: 自行車在線商城 REST API 文檔欧芽。
  version: ‘1.0’
servers:
  - url: https://api.server.test/v1
paths:
  /bikes:
    description: 自行車目錄
    get: 
      summary: 查詢自行車目錄
      description: |
        在自行車目錄中莉掂，使用關(guān)鍵詞，
        查詢匹配條件的自行車千扔。
      responses:
        “200”:
          description: |
            滿足查詢條件的自行車

我們添加了一個 responses 屬性憎妙，表示響應(yīng)的集合，包含操作所有可能的響應(yīng)曲楚。我們也添加了一個 "200" 響應(yīng)厘唾，表示 HTTP 對狀態(tài)碼，意思是操作成功龙誊。最后抚垃，description 屬性對響應(yīng)對內(nèi)容進行了說明。

響應(yīng)具體包含了哪些數(shù)據(jù)趟大，我們在后面對文章中進行詳細(xì)說明鹤树。

小結(jié)

是不是把設(shè)計轉(zhuǎn)換成語言描述很簡單？這說明我們對設(shè)計工作發(fā)揮了作用逊朽，讓接下來的工作水到渠成罕伯。等一等，還缺一個添加操作叽讳，請你動手寫出來吧追他。