api 文檔那些事之swagger

nodejs 搭載 swagger

• swagger ui是一個API在線文檔生成和測試的利器，目前發現最好用的。

環境搭建

• 下載swagger ui

git clone https://github.com/swagger-api/swagger-ui.git

• 建立一個空文件夾 node_app

npm init (生成package.json文件)

name: (node_app) node_app
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)

• 安裝 express

npm install express --save

• 建立index.js

var express = require('express');
var app = express();
app.use('/static', express.static('public'));
app.get('/api/person', function (req, res) { //返回的數據類型和url路徑要一至
  res.send([{
    "firstName": "s",
    "lastName": "s",
    "userName": "d"
  }]);
});


app.listen(3000, function () {
  console.log('Example app listening on port 3000!');
});

• 把下載好的Swagger UI 文件中dist 目錄下的文件所有複製到 public 文件夾下。
• 啓動： node index.js
• 打開瀏覽器 ，輸入http://localhost:3000/static/index.html

編寫文檔併發布

• 能夠用 Swagger Editor 編寫API文檔
• Swagger Editor 上的是基於 yaml 的語法
• 編寫好之後下載json文件
• 把swagger.json放到public文件下面
• 修改public文件下index.html頁面
• 從新啓動node index.html 和刷新頁面就能夠了

編寫api 文檔從零開始學習地址參考：Swagger從入門到精通

• 1.最簡單的例子

swagger: "2.0"

info:
 version: 1.0.0
 title: Simple API
 description: A simple API to learn how to write OpenAPI Specification

schemes:
 - https
 - http
host: 192.168.8.109:3000
basePath: /api

paths: {}

• 1.1 OpenAPI規範的版本號
  • 首先咱們要經過一個swagger屬性來聲明OpenAPI規範的版本。

swagger: "2.0"

• 1.2 API描述信息
  • 而後咱們須要說明一下API文檔的相關信息，好比API文檔版本（注意不一樣於上面的規範版本）、API文檔名稱已經可選的描述信息。

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

• 1.3 API的URL
  • 做爲web API，一個很重要的信息就是用來給消費者使用的根URL，能夠用協議（http或者https）、主機名、根路徑來描述：

schemes:
  - https
host: simple.api
basePath: /openapi101

• 這這個例子中，消費者把http://192.168.8.109:3000/api/person做爲根節點來訪問各類API

2. 定義一個API操做

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
  - http
host: 192.168.8.109:3000
basePath: /api

paths: 
  /person:
    get:
      summary: Gets some persons
      description: Returns a list containing all 
      responses:
        200:
          description:  A list of Person
          schema:
            type: array
            items:
              required: 
                - username
              properties:
                firstName:
                  type: string
                lastName: 
                  type: string
                userName:
                  type: string

• 如圖：

• 2.1 添加一個路徑（path）
  • 咱們添加一個/persons的路徑，用來訪問一組用戶信息：

paths:
  /persons:

• 2.2 在路徑中添加一個HTTP方法(get,post,put,delete)
  • 好比須要展現一組用戶信息，咱們能夠在/persons路徑中添加get方法，同時還能夠填寫一些簡單的描述信息（summary）或者說明該方法的一段長篇大論（description）

get:
      summary: Gets some persons
      description: Returns a list containing all persons.

• 2.3 定義響應（response）類型(返回狀態碼200，404，304，500等)

responses:
        200:
          description: A list of Person

• 2.4 定義響應內容
  • 經過響應消息中的模式（schema）屬性來描述清楚具體的返回內容。
  • 一組用戶信息就是一個用戶信息對象的數組（array），每個數組元素則是一個用戶信息對象（object），該對象包含三個string類型的屬性：姓氏、名字、用戶名，其中用戶名必須提供（required）。

schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

• 3.1 定義請求參數（query parameters）

#START############################################################################
      parameters:
       - name: pageSize
         in: query
         description: 要傳入每一頁面大小
         type: number
       - name: pageNumber
         in: query
         description: 要傳入的分頁數量
         type: number
      # END ############################################################################


    完整的類型
    swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
  - http
host: 192.168.8.109
basePath: /index

paths: 
  /person:
    get:
      summary: Gets some persons
      description: Returns a list containing all
      #START############################################################################
      parameters:
       - name: pageSize
         in: query
         description: 要傳入每一頁面大小
         type: number
       - name: pageNumber
         in: query
         description: 要傳入的分頁數量
         type: number
      # END ############################################################################   
      responses:
        200:
          description:  A list of Person
          schema:
            type: array
            items:
              required: 
                - username
              properties:
                firstName:
                  type: string
                lastName: 
                  type: string
                userName:
                  type: string

經過 get /persons?pageSize=20&pageNumber=2 來訪問第2頁的用戶信息（不超過20條）

• 3.1 在get方法中增長請求參數

paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons. The list supports paging.
#START############################################################################
      parameters:
# END ##############################

• 3.2 添加一個 get /persons/{username} 操做

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
host: simple.api
basePath: /openapi101

paths:
  /persons:
                username:
                  type: string
#START############################################################################
  /persons/{username}:
    get:
      summary: Gets a person
      description: Returns a single person for its username
# END ############################################################################