碼上快樂

相關內容    簡體    繁體

Swagger從入門到放棄

本文轉載自   查看原文   2018-05-04 10:54   2943    Default

如何編寫基於OpenAPI規范的API文檔

簡介

  • Swagger
  • Swagger是一個簡單但功能強大的API表達工具。支持的語言種類繁多
  • 使用Swagger生成API，我們可以得到交互式文檔，自動生成代碼的SDK以及API的發現特性
  • OpenAPI規范
  • OpenAPI規范是Linux基金會的一個項目，試圖定義一種用來描述API格式或API定義的語言，來規范RESTful服務的開發過程
  • OpenAPI可以幫助我們描述一個API的基本信息：
    • 有關API的一般性描述
    • 可用路徑
    • 在每個路徑上的可用操作
    • 每個操作的輸入輸出格式
  • OpenAPI規范這類API定義語言能夠更簡單、快速的表述API，尤其是在API設計階段作用比較明顯
  • 如何編寫API文檔
  • 編輯器采用在線編輯：https://editor.swagger.io/#
  •       swagger: "2.0"
      info:
      description: 
      version: "1.0.0"
      title: "Swagger Petstore"
      termsOfService: "http://swagger.io/terms/"
      contact:
          email: "apiteam@swagger.io"
      license:
          name: "Apache 2.0"
          url: "http://www.apache.org/licenses/LICENSE-2.0.html"
      host: "petstore.swagger.io"
      basePath: "/v2"
      tags:
      - name: "pet"
      description: "Everything about your Pets"
      externalDocs:
          description: "Find out more"
          url: "http://swagger.io"
      - name: "store"
      description: "Access to Petstore orders"
      - name: "user"
      description: "Operations about user"
      externalDocs:
          description: "Find out more about our store"
          url: "http://swagger.io"
      schemes:
      - "http"
      paths:
          /pet:
              post:
              tags:
                  - "pet"
              summary: "Add a new pet to the store"
              description: ""
              operationId: "addPet"
              consumes:
                  - "application/json"
                  - "application/xml"
              produces:
                  - "application/xml"
                  - "application/json"
              parameters:
                  -   in: "body"
                      name: "body"
                      description: "Pet object that needs to be added to the store"
                      required: true
                      schema:
                      $ref: "#/definitions/Pet"
              responses:
                  405:
                  description: "Invalid input"
              security:
              - petstore_auth:
                  - "write:pets"
                  - "read:pets"

從零開始

  •   swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
  {}
  • 顯示界面如下：
  • 首先要通過swagger屬性來聲明OpenAPI規范的版本
  • 然后需要說明API文檔的相關信息，比如API文檔版本、API文檔名稱、描述信息等
  • 最后作為webURL，一個很重要的信息就是用來給消費者使用的 根URL ，可以使用協議http或https、主機名、根路徑來描述：
        schemes: 
    - https
    host: simple.api
    basePath: /openapi101
    ```
  • 接下來就是寫API的操作，通過paths，然而這里沒有寫只是通過{}對象占用位置
  •   swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
  /persons:
      get:
      summary: Get some persons
      description: Returns a list containing all persons
      responses:
          200:
              description: A list of Person
              schema:
                  type: array
                  items:
                      required: 
                          - username
                      properties:
                          firstname:
                              type: string
                          lastname:
                              type: string
                          username:
                              type: string
  • 在上面的這些代碼中，做了以下的動作：
    1. 添加了/persons的路徑，用來訪問一組用戶信息
    2. 在路徑中添加了HTTP方法get，同時也有一些簡單的描述信息summary和description
    3. 定義響應類型responses，響應類型中添加了HTTP狀態碼200
    4. 定義了響應內容：通過響應消息中的schema屬性來描述清楚具體的返回內容。通過type屬性可知一組用戶信息就是一個用戶信息數組，每一個數組元素則是一個用戶對象，該對象包含三個string類型的屬性，其中username必須提供（required）
  • 定義請求參數
  •   paths:
  /persons:
      get:
      summary: Get some persons
      description: Returns a list containing all persons
      parameters: 
          -   name: pageSize
              in: query
              description: Number of persons returned
              type: integer
          -   name: pageNumber
              in: query
              description: Page number
              type: integer
  • 首先在get方法中添加了一個parameters屬性
  • 在參數列表中，添加了兩個參數pageSize和pageNumber的整形參數，並有簡單描述
  • 定義路徑參數
  •   swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
  /persons/{username}:
      get:
      summary: Get some persons
      description: Returns a list containing all persons
      parameters: 
          -   name: username
              in: path
              required: true
              description: The person's username
              type: string
          
      responses:
          200:
          description: A list of Person
          schema:
              type: array
              items:
                  required: 
                      - username
                  properties:
                      firstname:
                          type: string
                      lastname:
                          type: string
                      username:
                          type: string
  • 路徑參數、請求參數以及消息參數等的不同之處就在於in屬性的值不同，分別為path、query、body等。同時對於參數的類型可以使用type或者schema來定義，例如消息體參數如下：
  •   swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
      /persons:
          post:
          summary: Creates a person
          description: Adds a new person to the persons list
          parameters: 
              -   name: person
                  in: body
                  description: The person to create
                  schema:
                      required: 
                      - username
                      properties:
                          firstname:
                              type: string
                          lastname:
                              type: string
                          username:
                              type: string
          responses:
              200:
              description: OK
  • 如果是單個參數可以使用type進行定義例如integer，string ，array等，而如果是json類型的參數就需要使用schema類來定義。
  • 定義相應消息
  •   response:
      204:
          description:Persons successfully created
      400:
          description:Persons couldn't have been created
  • 簡化數據模型
  • 通過使用definition來定義可重用的對象。如下：
  •   swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
  /persons:
      post:
      summary: Creates a person
      description: Adds a new person to the persons list
      parameters: 
          -   name: person
              in: body
              description: The person to create
              schema:
                  $ref: '#/definitions/Person'
      responses:
          200:
          description: OK
          schema:
              $ref: "#/definitions/Person"
          
  definitions:
      Person:
          required:
              - username
          properties:
              firstname:
                  type: string
              lastname: 
                  type: string
              username:
                  type: string
  • 定義可重用的參數
  •   swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
      /persons/{username}:
          get:
              parameters: 
                  - $ref: '#/parameters/username'
          
              responses:
                  200:
                  description: fsafsf

  parameters:
      username:
          name: username
          in: path
          required: true
          description: The person's username
          type: string

高級定義

  • 字符串的長度和格式
  •   -   name: username
      in: path
      required: true
      description: fasfsa
      type: string
      pattern: "[a-z0-9]{8,64}"
      minLength: 8
      maxLength: 64
  • 日期和時間
  •   parameters: 
      - name: dateofBirth
        in: query
        description: fasfsaf
        type: string
        format: date
  • 枚舉類型
  •   code:
      type: string
      enum: 
          - DBERR
          - NTERR
          - UNERR
  • 高級參數
  • 參數的媒體類型
  • 在文檔的根節點下面添加：
  •   produces:
      - text/xml
  consumes:
      - application/json
      - application/xml
  • 高級響應消息
  • 要定義一個不帶消息體的相應消息，只需要寫響應狀態和描述即可
  •   responses:
      '204':
          description: Person successfully created
  • 與請求消息類似，必帶參數使用required來標識
  •   Person:
      required:
          - username
      properties:
          firstname:
              type: string
          lastname: 
              type: string
          username: 
              type: string
  • 分類標簽
  • tags: - Persons


免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。



猜您在找 Swagger 入門 TypeScript從入門到放棄(一) Nginx 從入門到放棄（一） Python從入門到放棄 python入門到放棄 Ldap 從入門到放棄(一) python 爬蟲《從入門到放棄》 Docker 從入門到放棄（一）安裝 QML 從入門到放棄 rust cargo 從入門到放棄
 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM