活版印字

Swagger 自動產生 html 文件

Posted at 2016-11-11 swagger API 

簡易版

編輯API內容

http://editor.swagger.io/#/

下載壓縮檔

選 tab 列的 generate server，下載 NodeJS 的版本，裡面已經內含你剛剛所編輯的 yaml 檔案，直接把這個壓縮檔解開，然後 npm install，接著 npm start。

開發版

初始化

1
2
3

git clone git@github.com:swagger-api/swagger-ui.git api-docs

cd api-docs && npm install

編輯API內容

http://editor.swagger.io/#/

編輯完後，匯出 swagger.json 檔案

更新成自己專屬的API文件

將剛剛下載的檔案放入 src/main/html/swagger.json，

編輯 src/main/html/index.html 的 url 變數

從 url = "http://petstore.swagger.io/v2/swagger.json";

改為 url = "/swagger.json";

這樣全部就完成了，執行吧 npm run serve

進階版

除了上面的步驟之外

新增一個 yaml 轉 json 的 gulp 任務

1
2
3
4
5
6
7
8
9
10

var fs = require('fs');
var path = require('path');
var yaml = require('js-yaml');

gulp.task('swagger', function() {
  var doc = yaml.safeLoad(fs.readFileSync('./api/swagger/swagger.yaml',
    'utf8'));
  fs.writeFileSync('./src/main/html/swagger.json', JSON.stringify(doc, null,
    ' '));
});

修改default task

從 gulp.task('default', ['dist', 'copy']);
改為 gulp.task('default', ['dist', 'swagger', 'copy']);

新增yaml檔

將編輯好的 yaml 檔案，放置在 ./api/swagger/swagger.yaml

npm run serve

原始碼範例