OpenAPI 3.0 規範-食用指南

概述

OpenAPI 3.0 規範由 8 個根對象組成：

openapi
info
servers
paths
components
security
tags
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 文件就誕生了，它的展示方式如下：

上面灰色的 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: "[email protected]"
  license:
    name: "Apache 2.0"
    url: "http://springdoc.org"
paths: {}

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

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

按照約定 description 應該向用戶展示如下信息：

描述整個 API 和如何使用它
爲用戶提供測試賬號和數據
其他任何用戶需要的信息都可以通過它來提供

servers 對象

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

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

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

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 中看到以下的示例效果：

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 中展示效果如下：

在 schemas 中展示

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

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 會顯示安全任何的相關標識，如下：

點擊 Authorize 會顯示更多的安全信息：

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

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 對於分組信息的展示，如下：

externalDocs 對象

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

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

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

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

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

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

總結

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

參考資料：

OpenAPI tutorial using Swagger Editor and Swagger UI: Overview OpenAPI 不錯的教程
OpenApi Openweathermap Example File 完整 OpenAPI 規範文件
Swagger Editor Swagger 提供的在線編輯 OpenAPI 文件工具

OpenAPI 3.0 規範-食用指南

概述

openapi 對象

info 對象

servers 對象

paths 對象

parameters 對象

responses 對象

components 對象

在 parameters 中重用對象

在 reponses 中重用對象

在 schemas 中展示

security 對象

tags 對象

externalDocs 對象

總結

SQL優化-20231016

HTTPS 是如何進行安全傳輸的？

加密的藝術：密文的創建和校驗

憑證管理揭祕：Cookie-Session 與 JWT 方案的對決

4A 安全之授權：編程的門禁，你能解開嗎？

身份認證的盡頭竟然是無密碼？

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結