手把手帶你入門之Swagger UI

關於Swagger UI,從官網找來一段介紹。 簡單的來講, Swagger UI就是API文件生成和測試利器。

Swagger UI is a dependency-freecollection of HTML, Javascript, and CSS assets that dynamically generatebeautiful documentation and sandbox from a Swagger-compliant API. BecauseSwagger UI has no dependencies, you can host it in any server environment, oron
your local machine. Head over to the online demo to see what it looks likefor any publically accessible Swagger definition.

 

本文以angular-swagger-ui, 一個Swagger UI的變體講解swagger ui在NodeJS專案中的基本的應用和常見的定製

 

安裝使用:

1.      安裝 angular-swagger-ui

bower install angular-swagger-ui –save

2.      Dependencies

angularJS

bootstrapCSS

3.      把Swagger UI加到你的webpage中

<scripttype=”text/javascript”>
    // If directive has parametertrusted-sources=”true”
    angular.module(‘yourApp’,[‘swaggerUi’]);
    …
    // OR if you choosed to use”ngSanitize”
    angular.module(‘yourApp’,[‘ngSanitize’,’swaggerUi’]);
    …
</script>

 

建立一個html元素

<divswagger-uiurl=”URLToYourSwaggerDescriptor(swagger.json的URL)”api-explorer=”true”></div>

    

把swagger-ui.min.js 和angular.min.js加到頁面中

<body>
    …
    <scriptsrc=”yourPathToAngularJS/angular.min.js”></script>
    <scriptsrc=”yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js”></script>
    <!– if you choosed to use”ngSanitize” –>
    <scriptsrc=”yourPathToAngularSanitize/angular-sanitize.min.js”></script>
</body>

 

把swagger-ui.min.css 和bootstrap.min.css加到頁面中

<body>
    <head>
        …
        <linkrel=”stylesheet”href=”yourPathToBootstrapCSS/bootstrap.min.css”>
        <linkrel=”stylesheet”href=”yourPathToAngularSwaggerUI/dist/css/swagger-ui.min.css”>
    </head>
</body>

 

4.      到這裡你就可以在你的頁面上看到類似下圖的API Explorer。

5.      另外的一些常見定製, 和error handler就不一一細說,具體可以參照
https://github.com/Orange-OpenSource/angular-swagger-ui

基本定製:

說到定製, 就不得不簡單介紹一下angular-swagger-ui的結構。 順帶簡單介紹一下遇到的一些定製

1.      從下圖中可以看到原始碼的結構很簡單,less/scripts/templates

swagger-ui.js 主要做幾件事, 獲取並解析swagger.json,渲染API到頁面, 並且獲取填入的引數值處理並提交request

swagger-model.js主要定義了一些識別object以及不同類別的處理程式碼以供swagger-ui.js呼叫

swagger-client.js主要執行最後的傳送請求, 以及返回結果的處理

2.      定製大致分為兩部分:

頁面的風格, 樣式, 佈局排版: 需要修改對應的css以及template也就是swagger-ui.html

Call API之前的一些特殊處理, 或者一些功能上面的定製,新增Oauth驗證等等, 就需要修改對應的js, 以swagger-ui.js為主

 

下面是我們定製後的API Explorer:預設的是Oauth資訊填寫,sidebar列出所有可用的resource和operation

點選operation之後如下圖分為簡單介紹,執行request和samplecode三個tab

3.      因為涉及到一些API的訪問限制和安全策略, 一般不建議直接訪問開放的API, 可以通過中轉分發這些訪問,也便於做安全校驗以及其他控制操作。