Swagger UI教程 API 文檔神器 搭配Node使用

前言

• swagger ui 是一個API在線文檔生成和測試的利器，目前發現最好用的。
• 為什么好用？ Demo 傳送門
  • 支持API自動生成同步的在線文檔
    • 這些文檔可用于項目內部API審核
    • 方便測試人員了解API
  • 這些文檔可作為客戶產品文檔的一部分進行發布
    • 支持API規范生成代碼，生成的客戶端和服務器端骨架代碼可以加速開發和測試速度

環境搭建

• 下載Swagger UI（也可以直接下載 zip 文件）

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

• 安裝 express
• 創建一個空文件夾 node_app

mkdir node_app

• 初始化 node ，創建package.json文件（）

?  ~ ? >cd node_ap
?  ~/node_app ? >npm init
// 下面的看你心情填寫
name: (node_app) node_app
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)

• 安裝 express

? ~/node_app git:(master) ? >npm install express --save

• 創建 index.js

?  ~/node_app git:(master) ? >vim index.js

• 把下面代碼貼如 index.js 中

var express = require('express');
var app = express();
app.get('/', function (req, res) {
  res.send('Hello World!');
});

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

• 在 node_app 中創建空目錄 public

?  ~/node_app git:(master) ? >mkdir public
?  ~/node_app git:(master) ? >cd public

• 修改路由

  ?  ~/node_app/public git:(master) ? >vim ../index.js
  //在文件第三行插入下面這句話
  app.use('/static', express.static('public'));

• 把下載好的Swagger UI 文件中dist 目錄下的文件全部復制到 public 文件夾下。
  
  

  目錄結構
• 開啟 node

  ?  ~/node_app git:(master) ? >node index.js

• 打開瀏覽器，輸入 http://localhost:3000/static/index.html

編寫文檔并發布

• 使用 Swagger Editor 編寫 API 文檔
  • Swagger Editor 上的是基于 yaml 的語法，但是不用害怕，看著官方的 demo 看個10分鐘就會了。
• 導出 test.json 文檔
  
  

  導出方式
• 把 test.json 放到 node_app/public 目錄下。
• 利用編輯器修改 url = "http://petstore.swagger.io/v2/swagger.json"; 為 url = "/static/test.json";
• 重啟 node 服務，瀏覽器中打開 http://localhost:3000/static/index.html 就是你自己寫的 api 文檔了

效果圖

自己寫的 API 接口

PUT請求

GET請求

POST 請求

DELETE 請求