如何在Linux環境下利用Swagger進行API文檔共享

1. 準備Linux環境基礎依賴
在Linux系統上，首先需要安裝Node.js和npm（Node.js包管理器），這是Swagger Editor和Swagger UI運行的基礎環境。以Ubuntu/Debian為例，可通過以下命令安裝：

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -  # 添加Node.js源
sudo apt-get install -y nodejs  # 安裝Node.js及npm

安裝完成后，通過node -v和npm -v驗證安裝是否成功。

2. 安裝并啟動Swagger Editor（可選，用于編寫/編輯API定義）
Swagger Editor是在線編寫和驗證OpenAPI規范的工具，支持實時語法檢查和預覽。

• 方式一：通過npm全局安裝

  sudo npm install -g swagger-editor  # 全局安裝Swagger Editor
  swagger-editor  # 啟動本地服務（默認端口8080）
  

• 方式二：使用Docker容器化部署（推薦，便于管理）

  docker pull swaggerapi/swagger-editor:v4.6.0  # 拉取最新版鏡像
  docker run -d -p 8080:8080 --name swagger-editor swaggerapi/swagger-editor:v4.6.0  # 運行容器
  

  啟動后，通過瀏覽器訪問http://<服務器IP>:8080即可使用Swagger Editor。

3. 安裝并啟動Swagger UI（用于可視化展示API文檔）
Swagger UI是將OpenAPI規范（YAML/JSON）渲染為交互式文檔的工具，支持“Try it out”等功能。

• 方式一：通過npm手動配置

  sudo npm install -g swagger-ui-express express  # 安裝依賴
  mkdir swagger-ui-project && cd swagger-ui-project  # 創建項目目錄
  

  創建index.js文件，配置靜態文件服務和Swagger UI：

  const express = require('express');
  const swaggerUi = require('swagger-ui-express');
  const swaggerDocument = require('./swagger.json');  // 引入OpenAPI定義文件
  const app = express();
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));  // 映射訪問路徑
  app.listen(3000, () => console.log('Swagger UI運行在 http://localhost:3000/api-docs'));
  

  啟動服務：node index.js。
• 方式二：使用Docker容器化部署

  docker pull swaggerapi/swagger-ui:v4.15.5  # 拉取鏡像
  docker run -d -p 8081:8080 --name swagger-ui -e SWAGGER_FILE=/app/swagger.yaml -v /path/to/swagger.yaml:/app/swagger.yaml swaggerapi/swagger-ui:v4.15.5  # 掛載定義文件
  

  訪問http://<服務器IP>:8081即可查看文檔。

4. 編寫OpenAPI規范文件（核心：定義API結構）
OpenAPI規范（YAML或JSON格式）是Swagger文檔的基礎，需描述API的路徑、操作、參數、響應、模型等信息。示例如下（swagger.yaml）：

swagger: '2.0'
info:
  title: Linux API文檔示例
  version: 1.0.0
  description: 用于演示Linux環境下的API文檔共享
basePath: /api/v1
schemes:
  - http
paths:
  /users:
    get:
      summary: 獲取用戶列表
      description: 返回所有用戶的ID和名稱
      responses:
        '200':
          description: 成功獲取用戶列表
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        example: 1
      name:
        type: string
        example: 張三

將上述文件保存為swagger.yaml（或swagger.json），放置在項目根目錄或指定路徑。

5. 集成Swagger到應用（可選，自動生成文檔）
若使用Spring Boot框架，可通過springdoc-openapi依賴自動生成OpenAPI規范，無需手動編寫：

• 添加Maven依賴：

  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
  </dependency>
  

• 配置應用屬性（application.properties）：

  springdoc.api-docs.path=/api-docs  # OpenAPI規范路徑
  springdoc.swagger-ui.path=/swagger-ui  # Swagger UI訪問路徑
  

• 啟動應用后，訪問http://<服務器IP>:8080/swagger-ui即可查看自動生成的文檔。

6. 共享API文檔的方法

• 直接通過公網IP訪問：若服務器有公網IP，可直接通過http://<公網IP>:8080（Swagger Editor）或http://<公網IP>:8081/api-docs（Swagger UI）訪問。
• 內網穿透（無公網IP）：使用Cpolar、ngrok等工具將本地服務映射到公網。例如，使用Cpolar配置Swagger Editor公網地址：

  curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash  # 安裝Cpolar
  sudo systemctl start cpolar  # 啟動服務
  cpolar http 8080  # 映射Swagger Editor的8080端口
  

  根據Cpolar返回的公網地址（如https://xxx.cpalr.com）訪問文檔。
• 權限控制（安全）：為避免未授權訪問，可通過以下方式增強安全性：
  • Docker容器權限：限制容器端口映射范圍（如僅允許內網IP訪問）。
  • Web服務器配置：使用Nginx/Apache添加Basic Auth認證，示例Nginx配置：

    server {
      listen 80;
      server_name your-domain.com;
      location /api-docs {
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/.htpasswd;  # 存放用戶名密碼的文件
        proxy_pass http://localhost:3000;  # 代理到Swagger UI服務
      }
    }
    

    通過htpasswd命令創建密碼文件：htpasswd -c /etc/nginx/.htpasswd admin。

通過以上步驟，即可在Linux環境下完成Swagger的部署與配置，實現API文檔的共享與協作。