Swagger從入門到放棄

時間 2019-11-09

標籤 swagger 入門放棄简体版

原文原文鏈接

如何編寫基於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、主機名、根路徑來描述：
YAML 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

1. Kettle從入門到放棄
2. Swift從入門到放棄
3. 從入門到放棄
4. Openstack從入門到放棄
5. Lombok從入門到放棄
6. HTTP從入門到放棄
7. ElasticSearch從入門到放棄
8. Maven從入門到放棄
9. git從入門到放棄
10. Django從入門到放棄
更多相關文章...
• Memcached入門教程 - NoSQL教程
• Neo4j數據庫入門教程 - NoSQL教程
• YAML 入門教程
• Java Agent入門實戰（一）-Instrumentation介紹與使用

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。