利用 swagger 編輯互動式線上文件

峰高谷深發表於2019-12-30
Swagger

第一步，下載swagger-ui

​ 下載後，解壓找到dist目錄下的index.html

 <script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "https://petstore.swagger.io/v2/swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region
      window.ui = ui
    }
  </script>

​ 修改url引數，可返回定義好的json或yaml檔案

​ 多域名分組將url引數改為

<script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        //url: "https://petstore.swagger.io/v2/swagger.json",
        urls:[
          {name:'後臺介面文件',url:"/swagger_yaml/swagger_admin.yaml"},
          {name:'前臺介面文件',url:"/swagger_yaml/swagger_home.yaml"}
        ],
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
    }
  </script>

第二步，定義介面yaml或json檔案，參考文件

swagger: "2.0"                      
info:
  version: 1.0.0
  title: 前臺介面文件
  description:
    前臺介面文件
    <li>域名：www.laravel.com</li>
  contact:
    name: PHP開發組
schemes:
  - http
  - https
host: www.laravel.com
basePath: /
produces:
  - application/json
tags:
  - name: news
    description: 新聞
paths:
  /news/list:
    $ref: 'admin/news/paths/list.yaml'

引數說明：

swagger: swagger版本                      
info: API相關資訊，也支援其他對你資訊，如license,contact等
  version: 版本號，如1.0.1
  title: 文件標題
  description:文件描述
  contact: 聯絡資訊
    name: 名稱
schemes:
  - http
  - https
host: www.laravel.com
basePath: /
所有API呼叫的基礎URL由host , schemes , basePath（根級別）組成
<scheme>://<host>/<basePath>/news/list
produces: 指定返回的內容型別
  - application/json
consumes: 指定處理請求的提交內容型別,隻影響與POST，PUT和PATCH等請求主體的操作。對於像GET這樣的無人機操作，它會被忽略
  - application/json
tags: 打標分組，與paths路徑中的tags匹配
  - name: 組名
    description: 組描述
paths: api路徑
  /news/list: 請求地址，路由引數可用{}定義，如/news/{id}
    $ref: 'admin/news/paths/list.yaml'

介面詳細資訊：

post: api請求方式
      tags: 標籤
        - news
      summary: 描述
      description: 描述
      parameters: 請求引數
      - name: 引數名稱
        type: 型別
        in: 引數位置，可使用的值 "query", "header", "path" or "cookie".
        required: 是否必須
        description: 描述
      responses: 響應
        200:
          schema:
            properties:
              status:
                type: string
                example:
                  success
                description: 狀態
              code:
                type: integer
                example:
                  200
                description: 狀態碼
              message:
                type: string
                example:
                  '成功'
              data:
                type: object
                description: 返回值
                properties:
                  title:
                    type: string
                    description: 標題
                    example:
                      慶餘年各大人物結局#新聞標題
                  content:
                    type: string
                    description: 內容
                    example:
                      慶帝死於五竹鐳射眼#新聞內容
        default:
          $ref: '../../../errorResponse.yaml'
本作品系原創（除文中說明外）， 採用《CC 協議》許可，轉載必須註明作者和本文連結

相關文章