OpenAPI 3.0 規範-食用指南

小二十七發表於2022-06-26
API

概述

OpenAPI 3.0 規範由 8 個根物件組成：

  1. openapi
  2. info
  3. servers
  4. paths
  5. components
  6. security
  7. tags
  8. externalDocs

OpenAPI 的其餘功能都是基於這 8 根物件擴充套件而成，凡是包含以上物件並且副檔名為 json，yaml 的檔案，我們可以將其視為符合 OpenAPI 規範的描述檔案 ，你可以在：API Editor 線上編輯器 中來驗證你的 OpenAPI 檔案是否符合規範，以下我們就主要介紹 8 個根物件的使用和擴充套件方法

openapi 物件

openapi 是最簡單也是最基礎的屬性，我們為 OpenAPI 新增第一個根物件屬性，指定使用的規範版本：

openapi: "3.0.2"

然後繼續補充資訊

openapi: "3.0.2"
info:
  title: openAPI Demo
  version: '1.0'
paths: {}

一個極簡的 OpenAPI 檔案就誕生了，它的展示方式如下：

image-20220617125753764
  • 上面灰色的 1.0 是指你 server 的版本
  • OAS3 指的是你所使用的 OpenAPI 規範的版本

info 物件

根節點的 info 物件主要包含以下資訊：

  • title： 標題
  • description: API 描述
  • version：版本號
  • license：許可證資訊
  • contact：聯絡人資訊
  • terms of service：服務條款

以下是 info 物件和屬性的示例：

openapi: "3.0.2"
info:
  title: openAPI Demo
  description: "This is an API program for teaching"
  version: '1.1'
  termsOfService: "https://openweathermap.org/terms"
  contact:
    name: "api developer"
    url: "http://myblog.cn"
    email: "youemai@gmail.com"
  license:
    name: "Apache 2.0"
    url: "http://springdoc.org"
paths: {}

以上內容的預覽效果如下：

image-20220617132722173

如果覺得 description 太過簡陋，它也支援 Markdown 語法顯示，效果如下：

image-20220617133225602

按照約定 description 應該向使用者展示如下資訊：

  • 描述整個 API 和如何使用它
  • 為使用者提供測試賬號和資料
  • 其他任何使用者需要的資訊都可以通過它來提供

servers 物件

servers 主要表示訪問服務端的基礎路徑，既在訪問介面前都會帶上該引數，示例如下：

servers:
  - url: 'http://localhost:8080/webapi'
image-20220618234009839

servers 物件支援多引數配置，你可以指定多伺服器（開發，測試，生成等）的 URL，使用者可以從下拉框選擇不用伺服器的 URL 發起請求，配置和預覽效果如下：

servers:
- url: https://localhost:8080/webapi
  description: develop server
- url: http://test-server:8080/webapi
  description: test server
- url: http://product-server:8080/webapi
  description: product server
image-20220618233542570

paths 物件

paths 物件包含真正的 API 資訊內容，它的每個項都包含一個可操作的 endpoint 操作物件，每個操作物件都包含我們常見的 GET/POST/PUT/DELETE 等方法，看一個簡單示例：

paths:
  /pet:
    get:

以上資訊描述一個 /pet 的 endpoint ，它只包含一個 get 操作物件，類似 get 操作物件（也稱 Operation Objects）也包含以下屬性：

  • tags：用於對 endpoint 進行分組的組名
  • summary：操作物件的摘要資訊，最好限制在 5-10 字以內，主要作為概覽展示
  • description：操作物件的描述資訊，儘可能的詳細，展示細節資訊
  • operationId：操作物件的唯一 ID
  • parameters：該端點的請求引數物件，描述如下，（ requestBody 描述不在此列包含系列屬）
    • name：引數名稱
    • in：引數出現的位置，通常是 header，path，query，cookie
    • description：引數的描述（支援 markdown）
    • required：必填項
    • deprecated：是否棄用
    • allowEmptyValue：允許提交空值
    • style：引數序列化方式
    • explode：與陣列相關的引數
    • schema：引數的模型
    • example：媒體型別的示例
  • requestBody：請求主體的描述，還可以包含一個指向 components 的 $ref 指標
  • response：響應主體的描述，通常使用標準的 HTTP 狀態碼，可以包含指向 components 的 $ref 指標
  • callbacks：回撥物件和回撥資訊的描述，較為少見，不過多介紹
  • deprecated：標識該 path 是否被棄用
  • security：僅用於覆蓋全域性的安全授權方法
  • servers：僅用於覆蓋全域性的伺服器訪問物件

大多數情況下不需要宣告那麼多的屬性，以下是一個端點的 operation object 常見描述資訊，如下：

paths:
  /weather:
    get:
      tags:
      summary:
      description:
      operationId:
      externalDocs:
      parameters:
      responses:

parameters 物件

parameters 的示例用法（包含一個引數的 get 方法）：

paths:
  /weather:
    get:
      tags:
      - Current Weather Data
      summary: "Call current weather data for one location."
      description: "^_^"
      operationId: CurrentWeatherData
      parameters:
      - name: q
        in: query
        description: "^_^"
        schema:
          type: string

responses 物件

responses 用於描述介面的響應物件，可以直接描述，如下：

responses:
  200:
    description: Successful response
    content:
      application/json:
        schema:
          title: Sample
          type: object
          properties:
            placeholder:
              type: string
              description: Placeholder description

  404:
    description: Not found response
    content:
      text/plain:
        schema:
          title: Weather not found
          type: string
          example: Not found

你可以在 Swagger UI 中看到以下的示例效果：

image-20220623211039935

components 物件

在 components 中主要可以定義重複使用的物件，以便其他物件使用 $ref 關鍵字直接引用和宣告

在 parameters 中重用物件

我們可以把剛才對 parameters 的描述移動到 components 中來，如下：

components:
  parameters:
    q:
      name: q
      in: query
      description: "………………"
      schema:
        type: string
    id:
      name: id
      in: query
      description: "…………"
      schema:
        type: string
    lat:
      name: lat
      in: query
      description: "………………"
      schema:
        type: string

然後我們可以在 paramters 中直接引用它，如下：

paths:
  /weather:
    get:
      tags:
      - Current Weather Data
      summary: "………………"
      description: "………………."
      operationId: CurrentWeatherData
      parameters:
        - $ref: '#/components/parameters/q'
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/lat'
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                title: Sample
                type: object
                properties:
                  placeholder:
                    type: string
                    description: Placeholder description
        404:
          description: Not found response
          content:
            text/plain:
              schema:
                title: Weather not found
                type: string
                example: Not found

如上，利用好 components 就可以達到元件複用 +減少篇幅的效果

在 reponses 中重用物件

我們也可以直接在 reponses 中引用已經宣告的物件，如下：

responses:
  200:
    description: Successful response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/200'

它在 yaml 中的描述如下：

components:
  schemas:
    200:
      title: Successful response
      type: object
      properties:
        base:
          type: string
          description: Internal parameter
          example: cmc stations
        visibility:
          type: integer
          description: Visibility, meter
          example: 16093
        dt:
          type: integer
          description: Time of data calculation, unix, UTC
          format: int32
          example: 1435658272
        id:
          type: integer
          description: City ID
          format: int32
          example: 2172797
        name:
          type: string
          example: Cairns
        cod:
          type: integer
          description: Internal parameter
          format: int32
          example: 200

它在 Swagger UI 中展示效果如下：

image-20220623221100016

在 schemas 中展示

通過 components 定義的物件都會在 Swagger UI 下方通過 Schemas 進行展示，如下：

image-20220623221314193

security 物件

除了部分 Demo 示例外，大部分的 Web 服務都是需要經過身份認證的才能訪問，security 就是用於描述 API 的安全資訊和訪問授權協議等資訊的物件，OpenAPI 支援最常見的四種授權方案，如下：

  • API key
  • HTTP
  • OAuth 2.0
  • Open ID Connect

這裡我們使用最常見的 API Key 作為演示，在 OpenAPI 文件的根目錄新增安全物件：

security:
  - app_id: []

這樣所有的路徑都會使用 security 描述的 app_id 安全方法，但是通常會在 components 中新增 security 物件，這樣的描述資訊會更加的詳細，如下：

components:
  ...
  securitySchemes:
    app_id:
      type: apiKey
      description: API key to authorize requests.
      name: appid
      in: query

security 物件的屬性內容：

  • type：授權協議，列舉值有：apiKey、http、oauth2、openIdConnect
  • description：安全方法的描述，儘可能的詳細，包含使用示例
  • name：安全金鑰 apiKey 在 HTTP Header 請求中的名字
  • in：安全金鑰 apiKey 在 HTTP 傳輸中的位置，列舉值有：query，header，cookie
  • …………

在新增以上的描述資訊後，Swagger UI 會顯示安全任何的相關標識，如下：

image-20220626001754782

點選 Authorize 會顯示更多的安全資訊：

image-20220626001929858

當你在 Value 輸入你的訪問祕鑰時，Swagger 會在訪問 API 的時候，根據你的設定訪問你的 API，如下：

image-20220626002200263

tags 物件

該物件主要是對 OpenAPI 中的多個訪問路徑進行分組，從而更方面的檢視 API 資訊，使用示例如下：

我們為一個請求路徑新增 tags 資訊：

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets

這表示該請求路徑屬於 pets 分組，然後我們在根目錄級別新增 tags 屬性，來為分組資訊進行描述：

tags:
  - name: pets
    description: "Chimelong Animal Happy World"

然後我們來看看 Swagger UI 對於分組資訊的展示，如下：

image-20220626003256305

externalDocs 物件

該物件不常用，主要新增對外部文件的引用，來對目前文件進行補充，例如你可以在根目錄新增該屬性，如下：

externalDocs:
  description: externalDocs API Documentation
  url: https://openweathermap.org/api

它會在你 Swagger 的描述中展示一個連結地址，如下：

OpenAPI 3.0 規範-食用指南

你還可以在 API 的請求路徑中，增加一個外部引用的描述，如下：

paths:
  /pets:
    get:
      summary: List all pets
      externalDocs:
        description: externalDocs API Documentation
        url: https://openweathermap.org/api

Swagger UI 會在請求路徑的描述中，增加一個外部連結作為對描述的補充，如下：

image-20220626004102765

總結

以上就是一個完整的 OpenAPI 規範的檔案的使用說明

參考資料：

相關文章