如何在Linux上使用Swagger進行API文檔管理

在Linux上使用Swagger進行API文檔管理，通常涉及以下幾個步驟：

安裝Swagger UI和Swagger Editor

1. 安裝Swagger UI：

• 更新包列表：

sudo apt update

• 安裝必要的依賴：

sudo apt install -y openjdk-11-jre-headless

• 下載并解壓Swagger UI：

wget https://repo1.maven.org/maven2/io/springfox/springfox-swagger-ui/2.9.2/springfox-swagger-ui-2.9.2.html
unzip springfox-swagger-ui-2.9.2.html

• 移動解壓后的文件到Web服務目錄（例如 /var/www/html）：

sudo mv springfox-swagger-ui-2.9.2 /var/www/html/swagger-ui

• 配置Swagger UI（可選）： 編輯 /var/www/html/swagger-ui/index.html 文件，找到以下行并進行修改：

script
window.onload = function() {
  // Begin Swagger UI call region
  const ui = SwaggerUIBundle({
    url: "http://petstore.swagger.io/v2/api-docs",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });
  // End Swagger UI call region
  window.ui = ui;
};
// script

• 啟動Web服務器（例如Apache或Nginx）：

• 對于Apache：

sudo a2ensite default.conf
sudo systemctl restart apache2

• 對于Nginx：

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.backup
sudo nano /etc/nginx/sites-available/default

修改server塊中的root和index指令：

server {
  listen 80 default_server;
  listen [::]: 80 default_server;
  root /var/www/html;
  index index.html index.htm;
  server_name _;
  location / {
    try_files $uri $uri/ =404;
  }
}

保存并退出編輯器，然后重啟Nginx：

sudo systemctl restart nginx

2. 安裝Swagger Editor：

• 下載Swagger Editor：

wget https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.50.0/swagger-editor.min.js
wget https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.50.0/swagger-editor.min.css

• 移動文件到Web服務目錄（例如 /var/www/html）：

sudo mv swagger-editor.min.js /var/www/html/swagger-editor.js
sudo mv swagger-editor.min.css /var/www/html/swagger-editor.css

• 創建一個簡單的HTML文件來加載Swagger Editor：

sudo nano /var/www/html/swagger-editor.html

添加以下內容：

!DOCTYPE html>
html
head
link rel="stylesheet" type="text/css" href="swagger-editor.css">
/head
body
div id="swagger-editor">
/div
script src="swagger-editor.js">
/script
script
window.onload = function() {
  const editor = SwaggerEditor({
    url: "https://petstore.swagger.io/v2/api-docs",
    dom_id: '#swagger-editor'
  });
};
/script
/body
/html

• 啟動Web服務器（例如Apache或Nginx）：

• 對于Apache：

sudo a2ensite default.conf
sudo systemctl restart apache2

• 對于Nginx：

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.backup
sudo nano /etc/nginx/sites-available/default

修改server塊中的root和index指令：

server {
  listen 80 default_server;
  listen [::]: 80 default_server;
  root /var/www/html;
  index index.html index.htm;
  server_name _;
  location / {
    try_files $uri $uri/ =404;
  }
}

保存并退出編輯器，然后重啟Nginx：

sudo systemctl restart nginx

配置和訪問Swagger UI和Swagger Editor

• 訪問Swagger UI：在瀏覽器中輸入 http://your_server_ip/swagger-ui。
• 訪問Swagger Editor：在瀏覽器中輸入 http://your_server_ip/swagger-editor。

權限管理

Swagger本身不直接提供權限管理功能，但你可以通過以下幾種方法來實現權限管理：

• 使用OAuth 2.0：在Swagger配置文件中定義安全方案（security scheme），并將其應用到相應的API端點。
• 使用角色和權限：在后端服務中實現角色和權限的概念，并將它們與Swagger API文檔關聯起來。
• 使用訪問控制列表（ACL）：在后端服務中實現ACL，并根據用戶的權限來決定是否允許他們訪問特定的API端點。
• 使用第三方工具：使用OpenAPI-to-Swagger(OAST)工具來生成具有權限管理的Swagger文檔。

以上步驟和配置方法可以幫助你在Linux系統上成功安裝和配置Swagger，以便進行API文檔的管理和可視化。