<input id="ohw05"></input>
  • <table id="ohw05"><menu id="ohw05"></menu></table>
  • <var id="ohw05"></var>
  • <code id="ohw05"><cite id="ohw05"></cite></code>
    <label id="ohw05"></label>
    <var id="ohw05"></var>
  • OpenAPI 3.0 規范-食用指南

    概述

    OpenAPI 3.0 規范由 8 個根對象組成:

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

    OpenAPI 的其余功能都是基于這 8 根對象擴展而成,凡是包含以上對象并且擴展名為 jsonyaml 的文件,我們可以將其視為符合 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:
    

    以上信息描述一個 /petendpoint ,它只包含一個 get 操作對象,類似 get 操作對象(也稱 Operation Objects)也包含以下屬性:

    • tags:用于對 endpoint 進行分組的組名
    • summary:操作對象的摘要信息,最好限制在 5-10 字以內,主要作為概覽展示
    • description:操作對象的描述信息,盡可能的詳細,展示細節信息
    • operationId:操作對象的唯一 ID
    • parameters:該端點的請求參數對象,描述如下,( requestBody 描述不在此列包含系列屬)
      • name:參數名稱
      • in:參數出現的位置,通常是 headerpathquerycookie
      • 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:授權協議,枚舉值有:apiKeyhttpoauth2openIdConnect
    • description:安全方法的描述,盡可能的詳細,包含使用示例
    • name:安全密鑰 apiKey 在 HTTP Header 請求中的名字
    • in:安全密鑰 apiKey 在 HTTP 傳輸中的位置,枚舉值有:queryheadercookie
    • …………

    在添加以上的描述信息后,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 的描述中展示一個鏈接地址,如下:

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

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

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

    image-20220626004102765

    總結

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

    參考資料:

    posted @ 2022-06-26 00:50  小二十七  閱讀(241)  評論(1編輯  收藏  舉報
    国产美女a做受大片观看