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

本文轉載自查看原文 2017-01-09 10:37 2136 Web API

ASP.NET Web API 使用Swagger生成在線幫助測試文檔

Swagger 生成 ASP.NET Web API

前言

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

總結一句話就是好用，逼格高。下面我將總結一下如何快速在本地搭建一個基於Node和Swagger UI的 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

到此為止，你已經把官方的 demo 在本地配置好了。當然你也可以吧這個搭建在服務器上

編寫文檔並發布

使用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 文檔了