建立現代化的 API 文件 with Swagger

API 文件管理 with Swagger

API Framework / Platform

處理 API 文件、體驗介面與工具鏈的支援

Swagger – The World’s Most Popular Framework for APIs.

Apiary | Platform for API Design, Development & Documentation

延伸閱讀

Swagger 有哪些功能

  • generator code
  • 動態文件產生器
  • 動態 API 的呼叫介面

誰有使用 Swagger

  • Paypal
  • Microsoft
  • Amazon AWS API gateway

Swagger 工具鍊

  • Swagger Code Generator
  • Swagger Editor, server code generator, client code generator:
    • swagger 的線上編輯器,可匯入匯出或格式轉換工具,並產生 client / server side 的程式碼下載,支援多種語言。
  • Swagger UI:
    • HTML based API document & API test runner。從 swagger definitions 產生一組 HTML UI, 能夠直接查閱 API 的說明及用法, 甚至包含線上的測試工具,讓你直接免工具就可呼叫 API 看看結果。
  • Tools & Integration:

Swagger Editor

  • swagger 的線上編輯器,匯入匯出及格式轉換工具,到產生 client / server side code

Swagger UI

  • 從瀏覽器以視覺化的方式,測試以 Swagger 定義的 REST API。
  • 內建的測試功能,可讓您以圖形方式來探索 API、測試 API 和檢查結果。

自訂Swagger UI 頁面

  1. 先抓 source code Github - swagger-ui
  2. 將編譯好的 swagger.json 放置在 dist 目錄下
  3. index.html 裡可以設定語系
  4. 更改 index.html 下的 url 改成自己的檔案位置 http://www.your-domain/swagger.json
  5. 將 dist 整個資料夾部署到 http server

Swagger CodeGen

  • 支援多種語言 nodejs, java, ruby, go...
  • 可產生各種語言的 server 端的 code
git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
mvn clean package
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate  -i http://petstore.swagger.io/v2/swagger.json  -l nodejs-server  -o samples/server/petstore/nodejs
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l spring -o samples/server/petstore/spring

延伸閱讀

若完全無 API 的狀態,從何開始?

  • 先用 IDE 編寫好 Swagger definition
  • 之後匯出 JSON 檔
  • 再把 JSON 檔匯入至 Swagger Codegen 產生出 server 端的 code

Swagger 文件說明 (specification)

必要的欄位

  • swagger
  • info
  • paths

最基本範例

swagger: '2.0'
info:
  version: 0.0.0
  title: Simple API
paths:
  /:
    get:
      responses:
        200:
          description: OK

Security Definitions Object Example

securityDefinitions:
  api_key:
    type: apiKey
    name: api_key
    in: header
  petstore_auth:
    type: oauth2
    authorizationUrl: http://petstore.swagger.io/api/oauth/dialog
    flow: implicit
    scopes:
      write_pets: modify pets in your account
      read_pets: read your pets

Swagger Hub

練習題

  • 以 API 使用說明書為例子,改寫成 Swagger 格式的文件,並把 json 下載下來,commit 到 Git。

Video

更多用 Swagger 製作文件的例子

延伸閱讀

results for ""

    No results matching ""