Swagger在Linux环境下的配置指南

Swagger是一个流行的API文档工具，下面我将详细介绍在Linux环境下配置Swagger的步骤。

1. 安装Node.js和npm

Swagger UI通常需要Node.js环境：

# 对于Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# 对于CentOS/RHEL
sudo yum install nodejs npm

# 验证安装
node -v
npm -v

2. 安装Swagger UI

方法一：使用npm安装

npm install swagger-ui-express -g

方法二：下载Swagger UI发行版

wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.9.0.tar.gz
tar -xzvf v5.9.0.tar.gz
cd swagger-ui-5.9.0/dist

3. 配置Swagger

对于Node.js应用

1. 创建基本Express应用：

mkdir swagger-demo
cd swagger-demo
npm init -y
npm install express swagger-ui-express

2. 创建app.js文件：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

const app = express();

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

3. 创建swagger.json文件（示例）：

{
  "openapi": "3.0.0",
  "info": {
    "title": "Sample API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get all users",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

对于静态文件部署

1. 将Swagger UI的dist目录复制到你的web服务器目录
2. 修改dist/index.html中的URL指向你的API文档：

window.onload = function() {
  const ui = SwaggerUIBundle({
    url: "http://your-api-url/swagger.json",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  });
}

4. 使用Nginx配置（可选）

server {
    listen 80;
    server_name api.example.com;

    location /api-docs/ {
        alias /path/to/swagger-ui/dist/;
        try_files $uri $uri/ /index.html;
    }

    location /swagger.json {
        alias /path/to/your/swagger.json;
    }
}

5. 启动应用

对于Node.js应用：

node app.js

访问http://your-server:3000/api-docs查看Swagger UI界面。

6. 高级配置选项

使用Swagger Editor本地开发

docker pull swaggerapi/swagger-editor
docker run -d -p 8080:8080 swaggerapi/swagger-editor

使用Swagger Codegen生成客户端代码

wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.41/swagger-codegen-cli-3.0.41.jar -O swagger-codegen-cli.jar

java -jar swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l python \
  -o /tmp/python-client

常见问题解决

1. CORS问题：确保你的API服务器配置了正确的CORS头
2. 文件权限问题：确保web服务器对Swagger UI文件有读取权限
3. JSON格式错误：使用在线工具验证你的Swagger/OpenAPI文档格式

希望这个指南能帮助你在Linux环境下成功配置Swagger！