插件窝 干货文章 Swagger如何在Linux服务器上部署

Swagger如何在Linux服务器上部署

Swagger nginx sudo bash 513    来源:    2025-05-08

在Linux服务器上部署Swagger的详细指南

Swagger(现称OpenAPI)是一个用于设计、构建、文档化和使用RESTful API的强大工具。以下是在Linux服务器上部署Swagger的几种方法:

方法一:使用Swagger UI独立部署

1. 安装必要依赖

sudo apt update
sudo apt install -y nginx unzip

2. 下载Swagger UI

wget https://github.com/swagger-api/swagger-ui/archive/refs/heads/master.zip
unzip master.zip
mv swagger-ui-master /var/www/swagger-ui

3. 配置Nginx

sudo nano /etc/nginx/sites-available/swagger

添加以下内容:

server {
    listen 80;
    server_name your-domain.com; # 替换为你的域名或IP

    root /var/www/swagger-ui/dist;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

启用配置:

sudo ln -s /etc/nginx/sites-available/swagger /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

4. 配置Swagger UI

编辑/var/www/swagger-ui/dist/index.html,修改以下部分:

url: "https://petstore.swagger.io/v2/swagger.json", // 替换为你的API文档URL

方法二:使用Docker部署

1. 安装Docker

sudo apt update
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

2. 运行Swagger UI容器

docker run -d -p 8080:8080 -e SWAGGER_JSON=/foo/swagger.json -v /path/to/your/swagger.json:/foo/swagger.json swaggerapi/swagger-ui

方法三:作为Node.js应用部署

1. 安装Node.js

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt install -y nodejs

2. 创建Swagger项目

mkdir swagger-project && cd swagger-project
npm init -y
npm install swagger-ui-express express

创建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('Swagger UI running on http://localhost:3000/api-docs');
});

3. 运行应用

node app.js

安全考虑

  1. 启用HTTPS:使用Let's Encrypt免费证书

    sudo apt install certbot python3-certbot-nginx
    sudo certbot --nginx -d your-domain.com
    
  2. 添加基本认证

    location / {
       auth_basic "Restricted Content";
       auth_basic_user_file /etc/nginx/.htpasswd;
       try_files $uri $uri/ =404;
    }
    

    创建密码文件:

    sudo sh -c "echo -n 'username:' >> /etc/nginx/.htpasswd"
    sudo sh -c "openssl passwd -apr1 >> /etc/nginx/.htpasswd"
    

常见问题解决

  1. 跨域问题:确保你的API服务器配置了正确的CORS头
  2. 404错误:检查Nginx配置中的root路径是否正确
  3. Swagger UI空白页:检查浏览器控制台是否有JavaScript错误,确保API文档URL可访问

以上方法可以根据你的具体需求选择使用。对于生产环境,推荐使用Docker或Nginx部署方式,并确保配置适当的安全措施。