如何在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文档的共享与协作。

最新问答

相关标签