基於swagger的RESTfulAPI開發實踐

uyang發表於2015-12-25
SwaggerRESTAPI

前言

RESTful架構，是目前最流行的一種網際網路軟體架構。它結構清晰、符合標準、易於理解、擴充套件方便，所以正得到越來越多網站的採用。後端通過提供一套標準的RESTful API，讓網站，移動端和第三方系統都可以基於API進行資料互動和對接，極大的提高系統的開發效率，也使得前後端分離架構成為可能。
因此，不同的測試，開發團隊（前端，移動端，第三方接入者等）都需要圍繞API進行開發工作，API的規範和文件對於團隊開發，測試變得越來越重要。除了一份標準的文件，我們還希望API能夠線上測試使用，從而有更直觀的API使用體驗，降低API的學習成本。這些對於團隊的開發協作都會事半功倍。 
本文將介紹一些API文件和開發測試方面的一些實踐，使用typeson，docson，swagger-ui等開源工具，建立一個API的集設計，實現，測試，文件的一體化可視平臺，讓API的開發和使用更加高效。

概述

首先我們會通過一個簡單系統的RESTful API的開發，介紹如果利用typeson,docson,swagger-ui等工具輔助API的設計和開發，掌握這些工具的使用，提高API的開發效率，質量。

在這個例項的開發中，會涉及到以下規範和工具：

  • Swagger

    *Swagger是一種和語言無關的規範和框架，用於定義服務介面，主要用於描述RESTful的API。它專注於為API建立優秀的文件和客戶端庫。支援Swagger的API可以為API方法生成互動式的文件，讓使用者可以通過以視覺化的方式試驗，檢視請求和響應、標頭檔案和返回程式碼，從而發現API的功能。它本身就非常強大，但是Swagger框架還支援為多種流行的語言——包括JavaScript、Python、Ruby、Java、Scala等等——生成客戶端程式碼。*
*網址： https://helloreverb.com/developers/swagger*

  • Swagger-UI

    *為基於Swagger規範的API生成基於基於純粹HTML,javascript,css的線上視覺化文件，同時也能成為API的線上測試工具。*
*網址： https://github.com/wordnik/swagger-ui*

  • JSON Schema

    *類似於XSD對比與XML的關係，JSON schema是用來描述JSON資料型別的schema。*
*網址：http://json-schema.org/*

  • DOCSON

    *一個json資料的文件化工具，通過json schema生成對應的線上JSON視覺化文件。*
*網址：https://github.com/lbovet/docson*

  • TypeScript

    *TypeScript是一種由微軟開發的自由和開源的程式語言。它是JavaScript的一個超集，而且本質上向這個語言新增了可選的靜態型別和基於類的物件導向程式設計。*
*網址：http://www.typescriptlang.org/*

  • Typeson

    *利用typescript這種物件導向的javascipt超集，生成json schema。*
*網址：https://github.com/lbovet/typson*

在這個API的開發實踐中，我們會貫徹兩個理念：

  1. Design-First 設計先行
  2. TDD 測試驅動

從一個基本應用開始

 這部分我們假設開發團隊接到一個新的開發需求，開發一個客戶郵件營銷系統，註冊使用者可以管理自己的客戶，並通過郵件對客戶進行營銷活動。所有的後臺功能通過RESTful API形式提供服務，網站開發，移動端開發，和後端同時進行開發。
首先團隊之間需要溝通協調設計API介面設計，形成規範和文件。這就是我們常說的設計先行理念。

資料模型設計

可以看到如下頁面：
A1

說明docson已經準備好了

  • 第二步，根據業務需要設計json schema：

    1. 我們可以直接手寫json schema，入將以下檔案儲存為/examples/user.json：
"$schema":"http://json-schema.org/draft-04/schema#",
    "title":"User",
    "description":"使用者schema",
    "type":"object",
    "properties":{
        "id":{
            "description":"id",
            "type":"number"
        },
        "username":{
            "description":"使用者名稱",
            "type":"string"
        },
        "password":{
            "description":"密碼",
            "type":"string"
        },
        "fullname":{
            "description":"全名",
            "type":"string"
        },
        "telphone":{
            "description":"電話號碼",
            "type":"string"
        },
        "email":{
            "description":"Email",
            "type":"string"
        },
        "company":{
            "description":"公司名",
            "$ref":"#/definitions/Company"
        },
        "customers":{
            "description":"客戶",
            "type":"array",
            "items":{
                "$ref":"#/definitions/Customer"
            },
            "minItems":1,
            "uniqueItems":true
        },
        "mailTemplates":{
            "description":"模板",
            "type":"array",

將對應的地址http://localhost:8080/docson/examples/user.json 輸入docson，回車後將看到圖形化的schema：
A2

點選Customer等按鈕可以檢視對應的跟詳細的資料型別資訊：
A3

這樣所有人員都可以直接檢視資料模型的定義，協同設計。

  1. 除了手寫外，我們也可以利用Typescript/typeson來輔助我們生成json schema
    具體可以參考網站和demo：http://lbovet.github.io/typson-demo/ 需要稍微熟悉下typescript

A4

API介面的設計

在資料模型定義好後，我們接著可以定義具體需要的API列表和每個API的介面形式，請求方法，輸入輸出引數等具體資訊。在此我們利用前面設計好的json schema，結合swagger-ui工具，就可以定義設計API列表。
  • 第一步 準備好swagger-ui，部署並啟動。參考網址： https://github.com/wordnik/swagger-ui
    這裡我們將用swagger-ui的離線版本，先行設計API。
  • 第二步 設計每個API，按功能組織分類, 將設計好的json schema引入，同時設計如下API
"apis":[
        {
            "path":"/accounts/",
            "operations":[
                {
                    "parameters":[
                        {
                            "name":"account",
                            "description":"Create a new account",
                            "required":true,
                            "dataType":"Account",
                            "paramType":"body"
                        }
                    ],
                    "responseMessages":[
                        {
                            "code":401,
                            "message":"Unauthorized"
                        },
                        {
                            "code":500,
                            "message":"Internal Application Error"
                        }
                    ],
                    "httpMethod":"POST",
                    "notes":null,
                    "responseClass":"Account",
                    "nickname":"createAccount",
                    "summary":"Create a new account",
                    "produces":[
                        "application/json"
                    ]
                }
            ]
        },

完成後，我們將可以得到如下的API線上文件：
A5

如某個具體AP，獲取賬戶的具體資訊
A6

如果API已經準備好，或者後端提供了一個mock實現，那麼直接點選“try it out”,就可以直接呼叫該API，輸入測試資料，測試返回資料和錯誤資訊。

同時根據資料模型的json schema，swagger-ui 會自動生成對應json資料的form表單，無論結構多複雜，這極大方便API使用者對API的上手和測試。
A7

API的開發測試

到目前階段，我們可以看到，及時API完全沒有編碼實現，我們也有一個很清晰的API文件和測試環境。各個開發測試團隊可以在這個線上文件和測試平臺上，協同各自開發測試。比如：
  • API開發團隊根據這個文件，開發實現具體的API功能
  • 前端團隊或者移動端，根據這個API文件，分別獨自開發各自功能，mock API的實現。
  • 測試團隊可以直接根據這個API的測試平臺，利用selenium工具錄製測試指令碼和準備測試資料，在開發團隊實現前就可以把測試準備好，用測試驅動開發

API使用階段

 在API開發測試完成後，需要提供API給外部系統使用，我們可以直接把這個swagger-ui建立的線上文件和測試平臺提供給開發使用者，作為標準的文件和測試工具。這樣也不需要格外寫一份靜態的介面文件給使用者，我們提供的是一份標準的live文件和測試工具，可以極大的方便使用著瞭解API，減低使用者的學習成本。

總結

本文只是簡單的介紹了RESTful API開發中利用一些工具進行輔助開發，希望docson,typeson,swagger-ui 等純粹的基於html，javascript的前端工具能夠方便大家的API開發，建立一個API的線上文件和測試中心。這對於需要提供API服務給第三方的平臺開發者具有較大的價值。關於更多相關規範和工具的使用，希望大家參考對應網站提供的文件，深入掌握，也何以和作者交流


相關文章