在Golang中使用SwaggerUI實作API線上文檔

在Golang中使用SwaggerUI實作API線上文件

隨著現代化應用程式架構的出現，API（Application Programming Interface）已成為現代Web應用程式的基礎組成。隨著API數量的不斷增加，API文件的編寫和維護變成了一項繁瑣的任務。因此，簡化API文件的編寫和維護過程是非常必要的。 Swagger是一個受歡迎的解決方案，它為Web API提供了強大的文件化工具。本文將介紹如何在Golang中使用SwaggerUI實現API線上文件。

Swagger簡介

Swagger是一組開源的API建置工具，可以幫助開發人員設計、建置、文件化和測試RESTful API。它包括了Swagger Editor、Swagger UI和Swagger Codegen等多個工具。

其中，Swagger Editor是一個基於Web瀏覽器的編輯器，可以幫助開發人員編寫和編輯Swagger規格書，Swagger UI是一個可以將Swagger規格書渲染成API文檔的工具，Swagger Codegen可以自動產生客戶端和伺服器端API程式碼。

在Golang中使用SwaggerUI實作API線上文件

Golang是一種非常流行的程式語言，它的優點在於有很高的並發效能和低的開銷。它使用了稱為Goroutines的輕量級線程來處理並發，並且支援記憶體自動回收和垃圾回收。在Golang中，可以使用go-swagger函式庫來實作API線上文件。

1. 安裝Swagger

首先，需要安裝Swagger，可以透過下面的指令安裝：

$ brew tap go-swagger/go-swagger
$ brew install go-swagger

2. 初始化一個Golang專案

接下來，需要在本機上初始化一個Golang專案。使用下面的命令在本機電腦上建立了一個名為Go-Swagger-API的Golang專案：

$ mkdir Go-Swagger-API 
$ cd Go-Swagger-API 
$ go mod init Go-Swagger-API 

3. 建立API定義

##為了建立API定義，需要建立一個YAML文件，並在其中定義API設定。在本例中，可以建立一個文件名稱為pets.yaml的文件，並在其中加入以下程式碼：

swagger: "2.0"
info:
  version: 1.0.0
  title: Petstore API 
produces:
- application/json
paths:
  /pets:
    get:
      summary: List all pets 
      responses:
        200:
          description: OK
        500:
          description: Internal Server Error
    post:
      summary: Add a new pet 
      parameters:
        - in: body
          name: body
          schema:
            "$ref": "#/definitions/pet"
          required: true
      responses:
        201:
          description: Created
        500:
          description: Internal Server Error

definitions:
  pet:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      tag:
        type: string

產生API服務端框架

接下來，需要使用go-swagger工具產生程式碼，該程式碼產生器將自動使用上一個步驟中定義的組態產生程式碼。在終端機中輸入以下命令：

$ swagger generate server -A Go-Swagger-API -f pets.yaml

此命令將根據YAML檔案中的定義產生服務端框架。

啟動API伺服器

接下來，需要啟動API伺服器並驗證它是否正常運作。在終端機中輸入以下命令：

$ cd cmd/go-swagger-api-server/
$ go run main.go

輸出應該會類似於下面這樣：

Serving Go-Swagger-API at http://127.0.0.1:8080 

現在，應該可以在網頁瀏覽器中存取以下URL以驗證API是否正常運作：

http://127.0.0.1:8080/pets。

整合SwaggerUI

最後一步是在API伺服器中整合SwaggerUI。首先，在專案的根目錄下建立一個名為swagger-ui的目錄，並在其中下載SwaggerUI，可以透過下面的命令來實現：

$ mkdir swagger-ui && cd swagger-ui && wget https://github.com/swagger-api/swagger-ui/archive/v3.32.3.tar.gz && tar xfz v3.32.3.tar.gz --strip-components=1 && rm v3.32.3.tar.gz

接下來，在API伺服器的main.go文件中加入以下程式碼：

// Setup the SwaggerUI middleware
swaggerUI := http.FileServer(http.Dir("./swagger-ui/dist"))
r.PathPrefix("/docs").Handler(http.StripPrefix("/docs", swaggerUI))

此程式碼將SwaggerUI中的dist目錄作為靜態資源檔案公開，用於呈現實際的SwaggerUI。

現在，可以在瀏覽器中存取以下URL以查看自動產生的API文件：

http://localhost:8080/docs/index.html。

結論

在Golang中使用SwaggerUI實作API線上文件不難，這為API文件的撰寫和維護帶來了極大的便利。透過使用Swagger，可以自動為API產生文檔，同時後端工程師和前端工程師可以快速理解API介面。這大大簡化了API的開發，測試和文件編寫過程，讓開發人員更專注於業務邏輯的實作。

以上是在Golang中使用SwaggerUI實作API線上文檔的詳細內容。更多資訊請關注PHP中文網其他相關文章！