open api 規範例子

open api 規範例子

openapi: 3.0.3
info: # api 基本信息描述
  title: open api 規範學習
  description: 詳細說明
  version: 0.0.1 版本號
  contact:
    name: 作者名稱,能直接關聯郵件地址
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers: # 這是一個數組，提供服務器的連接信息。如果沒有提供 servers 屬性或者是一個空數組，那麼默認爲是url值爲 /
  - url: 'http://example.com/' # 直接指定一個地址
    description: 指定服務器地址 # 描述
  - url: '{http}{domain}:{port}' # 可通過參數控制的地址
    description: 自定義服務器地址
    variables: #一組變量和值的映射，這些值被用來替換服務器URL地 址內的模板參數。
      http: # 聲明參數名稱
        enum: # 枚舉類型
          - 'http://' # 自定參數1
          - 'https://' # 自定參數2
          - ''
        default: http:// # 必選.默認值
        description: http 方式 #參數名稱說明
      domain:
        default: example.com # 默認是輸入框模式
        description: 可輸入自定域名或IP地址
      port:
        default: '80'
        description: 可輸入自定端口
paths: # 路徑地址列表對象
  /: # 路徑名
    description: 首頁地址 # 可選描述字段
    get: # 請求模式
      responses: # 返回參數對象
        200: # 定義成功返回例子
          description: 返回成功的描述
          content:
            text/html: # 返回內容格式
              schema:
                type: string # 值類型
                default: 你好
      parameters: # 請求下參數配置對象
        - name: page # get 參數名稱
          in: query # get 模式
          description: get值page參數 # 參數描述
          required: false # 是否必填狀態
          schema:
            type: string # 值對象類型
            default: 1 # 默認值
          allowEmptyValue: true # 是否允許爲空
  /login:
    description: 路徑的描述字段
    summary: 描述包含的操作  #可選,描述包含的操作
    post:
      description: '登錄請求'
      responses: # 返回信息說明
        200:
          description: 返回成功的描述
          content:
            application/json:
              schema:
                type: string
      security: # 指定該請求下單獨的憑證對象
        - headerKey: []
      parameters:
        - name: page # 添加 get 參數
          in: query
          description: page 參數
          required: false
          schema:
            type: integer
            format: int32
            default: 1
      requestBody: # post 請求參數內容對象
        content:
          application/x-www-form-urlencoded: # 參數編碼類型
            schema:
              type: object # 格式
              properties:
                name: # 定義參數對象
                  description: '用戶名參數'
                  type: string
                  default: 'test'
                password:
                  description: '密碼參數'
                  type: string
                  default: '1234'
                  format: password
components: # 組件
  securitySchemes: # 必選，可用祕密憑證列表
    headerKey: # 聲明自定義憑證對象
      type: apiKey # 憑證類型 自定義鍵與值的模式
      name: token # http header 標頭鍵名
      in: header # 插入位置
      description: token 描述 # 憑證的描述
    tokenJWT:
      type: http # http 標準認證模式
      scheme: bearer # 憑證模式
      bearerFormat: JWT # 格式
      description: token 描述 2
security: # 所有接口可調用的祕密憑證列表
  - tokenJWT: [] # 對應組件內的數組名稱

參考資料：

OpenAPI-Specification/3.0.0.zhCN.md at master · fishead/OpenAPI-Specification (github.com)

OpenAPI Specification v3.1.0 | Introduction, Definitions, & More